@kontextmind/kxm 0.6.0

package/docs/vnext/synchronization.md

@@ -0,0 +1,172 @@
+# Hub synchronization contract
+
+> **Status.** `kxm.sync-event.v1` is a **schema-tested contract**. There is no
+> outbox table, sync transform, or hub ingestion in source. Implementation
+> begins in [Phase 8](../../plans/implementation-plan.md#phase-8-multi-project-hub-vnext).
+
+Synchronization is summary-first, project-scoped, at-least-once, and
+allowlist-based. The full local event is never placed directly in the outbox.
+
+## Representations
+
+### Local event
+
+The home Runtime's immutable recovery record. It may contain bounded local data
+or references to protected local content.
+
+### Sync-safe event
+
+A new object conforming to `kxm.sync-event.v1`. It is derived before the outbox
+and contains only schema-declared fields. It references its source event by ID
+and preserves the run sequence.
+
+```text
+local event
+→ choose allowed event fields
+→ apply project policy
+→ replace registered secret values
+→ remove absolute paths
+→ enforce type and length bounds
+→ classify/redact
+→ validate kxm.sync-event.v1
+→ append outbox row
+```
+
+A denylist-only sanitizer is insufficient.
+
+## Default policy
+
+```yaml
+prompts: title-only
+results: bounded-summary
+evidence: references
+artifacts: metadata
+fileChanges: paths-only
+rawLogs: false
+diffs: false
+environmentValues: false
+```
+
+Normal projects do not need to materialize this policy.
+
+## Field allowlist
+
+| Category | Synchronized by default | Excluded by default |
+|---|---|---|
+| Identity | Project, run, workflow, step, assignment, attempt, Runtime IDs | Local account names not needed for authorization |
+| Lifecycle | Event type, sequence, state, outcome, retry/transition counts | Raw child process output |
+| Recovery/control | Resolved effect policy, lease/fencing identity and expiry, actor identity, resolution action, supplied evidence refs | Unstructured operator/tool bodies or secret-bearing receipt URLs |
+| Time | UTC event times, monotonic-derived durations | Host clock internals |
+| Model | Exact provider/model/profile/tags, capability result | Provider tokens and raw requests |
+| Usage | Input/output/cache tokens, reported/estimated cost and currency | Provider billing credentials |
+| Prompt | Bounded display title and prompt hash | Full prompt |
+| Result | Bounded summary and outcome | Full model output or reasoning |
+| Repository | Logical ID, commit/ref/PR receipt, relative changed paths | Absolute paths, file content, diff |
+| Environment | Variable name, scope, resolution status, source kind/version | Values and low-entropy value hashes |
+| Evidence | ID, kind, hash, status, producer metadata permitted by policy | Evidence body |
+| Artifact | ID, kind, hash, size, classification, availability | Artifact bytes |
+| Error | Allowlisted class, component, retryability | Raw provider/tool error body |
+| Learning | Bounded candidate summary, confidence, evidence references | Raw reasoning or automatic activation command |
+| Secret | Reference name/version and grant status when required | Secret value, derived value, credential-store path |
+
+Repository paths are normalized, repository-relative, and policy-filtered.
+Sensitive-path policy may replace even a relative path with a classification or
+hash.
+
+## Schema-level exclusions
+
+`kxm.sync-event.v1` uses `additionalProperties: false` throughout its payload.
+It contains no generic `data`, `metadata`, `context`, `log`, `prompt`, `output`,
+free-form environment map, or `errorBody` escape hatch. Its `environment` field
+is a closed array of name/scope/status/source/version records and cannot carry
+values. Extensions require a new reviewed schema revision.
+
+The outbox stores only the already-derived sync object plus retry transport
+metadata. It does not retain the full local source payload for later redaction.
+
+## Redaction
+
+Before transformation, the Runtime registers resolved secret values with an
+in-memory redactor. The transform also removes:
+
+- bearer/API/SSH credential shapes;
+- absolute Windows, UNC, POSIX, and home paths;
+- disallowed control characters;
+- excessive text and collection sizes;
+- fields not selected by the schema;
+- content that violates project classification policy.
+
+High-entropy detection is defense in depth, not the primary boundary. Secret
+values MUST NOT be persisted merely to support later redaction.
+
+## Ordering and idempotency
+
+- The home Runtime assigns the run sequence.
+- The hub accepts an exact event once by `{projectId, runId, sequence}`.
+- Repeating identical bytes is idempotent.
+- Reusing a sequence with different content is a conflict and security alert.
+- A gap remains pending until filled or explicitly declared unavailable.
+- Hub projections never invent missing events.
+- A hub acknowledgement advances the outbox cursor; loss before acknowledgement
+  causes a safe transport retry.
+
+Synchronization delay does not pause local execution except when the next action
+requires a shared-operation lease.
+
+## Prompts and evidence on demand
+
+The hub normally displays the run title and bounded summary. When an authorized
+user requests more content:
+
+```text
+hub/TUI request
+→ home Runtime verifies project, actor, policy, and current availability
+→ Runtime redacts and bounds the selected content
+→ stream response
+→ retain only if an explicit artifact policy permits it
+```
+
+The UI labels live content and retention. An offline Runtime simply makes the
+local body unavailable; the hub does not substitute a summary as if it were the
+body.
+
+## Learning synchronization
+
+Candidates synchronize because the hub coordinates comparison and promotion.
+They remain evidence with explicit source references, confidence, and status.
+No candidate payload may contain tools, secret grants, approval state, or an
+automatic activation instruction.
+
+Offline runs may synchronize candidates after reconnecting. They cannot claim a
+new memory revision or promote one while offline.
+
+## Environment and secrets
+
+A safe environment record may say:
+
+```yaml
+name: DATABASE_URL
+scope: repository:api
+status: resolved
+source: secret-ref
+version: credential-version-7
+```
+
+It cannot include a value, a reversible encoding, a value hash for a
+low-entropy secret, or a local credential-store path.
+
+## Logs
+
+Structured lifecycle summaries synchronize. Raw harness, model, tool, build,
+and process logs stay in Runtime-local protected storage. An explicit reviewed
+policy may upload a redacted/encrypted log artifact, which remains an artifact
+transfer rather than an unrestricted event field.
+
+## Policy changes
+
+`kxm.project.v1` expresses only the safe default event policy. Expanding prompt,
+evidence, diff, artifact, or log transfer requires a future versioned content-
+transfer policy and schema; it cannot be enabled through an unknown field.
+Such expansion is permission-increasing, requires trust review, and affects
+future runs only. The active run records the policy revision used for every
+outbox transform.

package/docs/vnext/terminology.md

@@ -0,0 +1,240 @@
+# Canonical terminology
+
+Use these terms consistently in schemas, code, CLI help, TUI labels, events,
+and documentation.
+
+## Configuration and topology
+
+### Project
+
+A coordinated product or body of work. A project has one stable `projectId`,
+one authoritative Git-tracked project root, and one or more repositories.
+
+### Project root
+
+The single control Git root containing `.kxm/project.yaml`, project agent/model/
+workflow definitions, and project-scoped skills and knowledge.
+
+### Control repository
+
+The repository containing the project root. It may also contain application
+code and may therefore be a member repository.
+
+### Member repository
+
+A Git repository bound to a project under a stable logical `repositoryId`.
+Absolute local paths are host bindings, not project configuration.
+
+### Resource definition
+
+One minimal Git-tracked file defining a project, repository, agent, model
+profile, workflow, or environment override. For agents, models, and workflows,
+the path and filename determine type and identity.
+
+### Configuration revision
+
+The content hash of the complete validated resource bundle used by a run. It
+includes uncommitted project-root content when a validated dirty snapshot is
+used.
+
+### Memory revision
+
+An immutable identifier for the promoted factual state visible to a run.
+Candidates generated during the run do not change its pinned revision.
+
+## Runtime and execution
+
+### Runtime
+
+The auto-started per-user/per-machine KXM process that owns run execution,
+local event stores, workspaces, harness sessions, secrets resolution, and the
+synchronization outbox.
+
+### Home Runtime
+
+The one Runtime recorded in `homeRuntimeId` when a run is accepted. Ownership is
+immutable unless a later explicit takeover/fencing protocol is implemented.
+
+### Hub
+
+The optional multi-project service that submits run requests, grants leases,
+synchronizes safe events and promoted facts, and exposes aggregate read models.
+It is not an execution owner.
+
+### Executor
+
+A backend that prepares an assignment environment and supervises a process.
+`local` and `ssh` are executor kinds; `exe.dev` is the first built-in SSH
+profile.
+
+### Harness
+
+The coding-agent runtime inside an executor. Pi is the initial harness. A
+harness owns provider authentication and model-session mechanics.
+
+### Network policy
+
+An agent ceiling with these meanings:
+
+- `none`: no network-capable tools or executor access;
+- `provider-only`: only harness-owned model-provider traffic;
+- `restricted`: provider traffic plus destinations allowlisted by trusted
+  adapters or host policy;
+- `host`: normal network access of the Runtime OS user.
+
+This is a capability ceiling, not a guarantee of packet-level containment in
+the trusted-local release. Strong enforcement requires the later sandbox/
+container phase.
+
+### Coordinator
+
+The logical project agent that interprets workflow intent and emits structured
+commands. Every run receives a separate physical coordinator session.
+
+### Agent definition
+
+A Git-tracked logical role describing purpose and ceilings for models, tools,
+repositories, secrets, executor, and results.
+
+### Agent instance
+
+One logical occurrence of an agent in a step, identified within the run by
+`agentId` and `instanceNo`.
+
+### Physical agent session
+
+A harness conversation and process binding identified by
+`{runId, agentId, instanceNo, scopeEpoch}`.
+
+### Scope epoch
+
+A monotonically increasing integer that forces a clean session when repository,
+secret, tool, model, or disclosure scope narrows or otherwise becomes
+incompatible with retained history.
+
+## Workflow hierarchy
+
+### Run request
+
+A hub or local request asking a Runtime to start work. It is not a run until a
+Runtime accepts it and appends `run.created`.
+
+### Run
+
+One immutable-config execution of a workflow owned by one home Runtime.
+
+### Step
+
+One ordered top-level workflow state. Only one top-level step is active at a
+time. A step may contain bounded dynamic assignments.
+
+### Step attempt
+
+One entry into a step. A declared back-edge creates a new attempt; evidence from
+an earlier attempt does not satisfy a later one unless policy explicitly allows
+reuse.
+
+### Assignment
+
+One logical unit of agent or deterministic work inside the active step. Its
+`assignmentId` remains stable across recovery attempts.
+
+### Attempt
+
+One physical execution of an assignment, identified by a unique `attemptId`.
+Calling a new process a resume does not make it the same attempt.
+
+### Join policy
+
+The Runtime-enforced rule that determines whether an assignment panel has
+settled sufficiently for a step outcome. The coordinator cannot override it.
+
+### MOA
+
+A mixture-of-agents panel. The reviewed template default (see `fix.yaml`) is three provider-distinct isolated
+instances, all-settled, with at least two valid completions before coordinator
+synthesis. The compiled kind default stays a single assignment until Phase 7.
+
+## Evidence and effects
+
+### Evidence reference
+
+A durable identifier or hash for a result, receipt, artifact, test, message, or
+other record. A caller-authored description is not proof of an external effect.
+
+### Producer policy
+
+A requirement that counts distinct Runtime-observed assignment producers from
+a declared eligible agent set for one exact run, step, and step attempt. A
+producer is bound to its assignment, physical attempt, agent definition, scope
+epoch, and pinned model. Multiple results from one assignment count once.
+Distinct producer records prove routed execution provenance, not correctness,
+non-collusion, or human independence.
+
+### Artifact
+
+Content produced or consumed by a run and managed under a declared retention
+and transfer policy. Hub synchronization carries metadata by default, not the
+content.
+
+### Effect
+
+A read or mutation caused by a tool, gate, delivery adapter, or executor action.
+Every effect has a Runtime-owned classification used for recovery.
+
+### Receipt
+
+A durable, queryable external identifier proving the observed outcome of an
+effect, such as an exact Git ref, pull request ID, or deployment ID.
+
+### Lease
+
+A time-bounded hub grant fencing a shared mutable action. A lease is not needed
+for local work or uniquely namespaced external work.
+
+### `blocked_uncertain`
+
+A durable state meaning KXM cannot prove whether a non-idempotent or unknown
+effect occurred. It forbids automatic replay until deterministic reconciliation
+or an audited human resolution supplies evidence.
+
+## Context and improvement
+
+### Temporal state
+
+Promoted factual project state with current, superseded, proposed, and rejected
+lifecycle records. It informs work but does not grant capabilities.
+
+### Candidate
+
+A proposed KB, skill, workflow, agent, model, environment, or template change
+with evidence and evaluation state. A candidate is not active configuration.
+
+### Promotion
+
+An authorized decision to make a factual state current or to accept a reviewed
+Git change. Offline runs may propose candidates but cannot promote hub state.
+
+## Observability
+
+### Local event
+
+The complete Runtime event used for local recovery and projection. It may refer
+to protected local content.
+
+### Sync-safe event
+
+An allowlisted, bounded, redacted derivative placed in the Runtime outbox. It
+contains no local payload by construction.
+
+### Active time
+
+Wall-clock interval from run creation to terminal settlement.
+
+### Agent time
+
+The sum of assignment-attempt execution durations. It may exceed active time
+when assignments overlap.
+
+Durations use monotonic clocks. UTC timestamps exist for display and audit, not
+for duration arithmetic.