Object Ecosystem & Ontologic Contracts

KDCube lets independently built apps become one interactive object ecosystem by exposing canonical object refs, named-service operations, conversation 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 a shared contract instead of hardcoded component logic.

Two buses serve different ownership domains, not different payload sizes. The Conversation Event Bus carries prompts, attachments, follow-ups, steer requests, and other context intended for a current or future conversation turn. The Data Bus carries app-owned domain mutations handled by @data_bus_handler(...), independently of chat. A Data Bus handler must explicitly submit conversation events when its result should enter or wake a conversation. Files and other bytes travel through storage and hosting contracts, referenced from events or tool results rather than embedded in model context.

i
Core idea: a namespace such as mem, task, cnv, or the conversation-owned conv:fi realm owns object identity. Surfaces render and move those objects. Providers explain how to search, open, materialize, and render them.
i
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 Conversation Event Bus carries ordered context into conversation turns. The Data Bus carries app-owned domain work to declared handlers. Outbound UI events use the communicator, while files and materialized objects use storage plus references; neither belongs to the Data Bus merely because it is not chat text.

i
Workspace is not timeline: the Agent Harness workspace owns files, physical paths, refs, byte materialization, and WorkspaceArtifact. The harness timeline owns ordered blocks, event identity, persisted payloads, turn logs, and client turn views. A file can exist without a timeline block, and a progress or note block is not automatically an artifact.

Named-Service Journey

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

  1. 1

    Object ref appears

    A user, widget, event, search result, or agent sees a canonical ref such as mem:record:... or task:issue:....

  2. 2

    Consumer checks policy

    surfaces.as_consumer declares which namespaces and operations the app or agent may call. User settings can narrow that configured ceiling. Tool traits govern ordered action compatibility and completed-call scheduling; they are not authorization.

  3. 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. 4

    Action, search, or materialization runs

    Provider operations such as object.search, object.action, and object.get return refs, effects, or materializable data. ReAct-facing callable names, such as search_objects, are separate from provider operation names. Before the first action in a namespace, the agent reads object.schema and uses only the payload keys that provider declares.

  5. 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. 6

    Timeline projection can render

    If a provider declares block.render, the renderer can ask it to patch only blocks owned by that provider namespace or event source. Neighboring blocks may be bounded context, but are not writable. Calls are traced as declared, called, rendered, empty, or error.

ref: mem:record:123
  -> named service discovery: namespace mem
  -> react.pull materializes conv:fi:conv_...turn_...files/materialized/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

A canonical conversation file ref includes two distinct ownership levels: conv: is the owning realm, while conv_<conversation_id> is the conversation owner segment inside a ref such as conv:fi:conv_...turn_...files/report.md. Refs are locators, not credentials; tenant, project, user, authority, and grants come from trusted runtime context.

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 two first-class trait families: strategy governs ordered multi-action compatibility, while execution governs when a completed call may start and how retries are replayed. Python tools, MCP tools, and named-service connections converge into this same runtime policy plane.

StrategyOrdered-causality meaningRuntime behavior
explorationObserves information that later actions may depend on.Compatible only where the ordered strategy matrix allows it.
exploitationActs on information or changes state.Ordered after its dependencies; never treated as a mere read/write label.
neutralHas no ordered dependency on sibling results.Required by the current early-execution profile.
unknownNo trustworthy causality classification is available.The tool remains callable, but runs alone.

The supported execution profile is trigger=tool_call_complete, concurrency=parallel_with_generation, result_dependency=detached, and replay=at_most_once_per_round. A call starts only after its complete action block passes the ordinary overseer, decision, protocol, and parameter validation. Detached means no same-round sibling consumes its result and it consumes no sibling result. Retry deduplication is round-scoped, not process-global exactly-once delivery, so externally visible actions should still be idempotent where possible.

Provider and Consumer Checklists

Provider publishes

  • Nouns: typed object kinds, self-contained refs, and one-line descriptions.
  • Questions: the self-described search vocabulary and filter schema.
  • Named, bounded use cases and the provider operations that serve them.
  • Guards: internal realm rules or connected-account requirements and real per-operation claim differences.
  • A human presentation layer: purpose, works_with or third_party, labels, user-term descriptions, and claim labels.
  • Registration metadata and tests for both projections: agent schema and user service card.

Consumer configures

  • Allowed namespaces and operations under surfaces.as_consumer.
  • Per-tool and per-namespace strategy and execution 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; providers authorize the trusted caller identity and grants for the selected mode: app credential, delegated per-user/per-agent identity, or connected provider account.