Skip to content

root-source-cutover-record.md

Latest commit

 

History

History
254 lines (195 loc) · 6.36 KB

root-source-cutover-record.md

File metadata and controls

254 lines (195 loc) · 6.36 KB

Root Source Cutover Record

Summary

The YAI native repository now uses a compressed canonical layout:

  • source implementation lives under src/<plane>
  • headers live under include/yai/<plane>
  • protocol contracts live under protocols/{schemas,fixtures,conformance,refs,registry}
  • repository meta-agent instructions live under .agents
  • historical/audit material remains under Documentation/archive and Documentation/internal

Final Canonical Source Planes

src/agents
src/analytics
src/capabilities
src/case
src/control
src/governance
src/knowledge
src/lineage
src/models
src/orchestrator
src/orchestrator/workflow
src/providers
src/runtime
src/runtime/access
src/state

memory is registered as a native plane direction, but physical extraction is deferred and no src/memory tree is created by this cutover stack.

Final Canonical Header Planes

include/yai/agents
include/yai/analytics
include/yai/capabilities
include/yai/case
include/yai/control
include/yai/governance
include/yai/knowledge
include/yai/lineage
include/yai/models
include/yai/orchestrator
include/yai/orchestrator/workflow
include/yai/providers
include/yai/runtime
include/yai/runtime/access
include/yai/state

memory is registered as a native plane direction, but physical header extraction is deferred and no include/yai/memory tree is created by this cutover stack.

Protocol Surface

protocols/schemas
protocols/fixtures
protocols/conformance
protocols/refs
protocols/registry

Major Corrections

Source Root Compression

Old root source planes were moved under src/.

Header Namespace

Old direct include/<plane> headers were moved under include/yai/<plane>.

Protocol Normalization

Old direct protocol folders were absorbed into canonical protocol children:

protocols/topology  -> protocols/registry/topology
protocols/naming    -> protocols/refs/naming
protocols/ontology  -> protocols/refs/ontology
protocols/system    -> protocols/refs/system

Lineage

lineage is a first-class native plane.

It is not owned by Knowledge.

Orchestrator / Workflow

flow is no longer a native canonical plane.

Operational workflow material lives under:

src/orchestrator/workflow
include/yai/orchestrator/workflow

Runtime Access

identity is not a native top-level plane.

Identity/account/auth/authorization/entitlement/machine authorization concepts are consumed locally as runtime access projections under:

src/runtime/access
include/yai/runtime/access

The local runtime does not own platform identity.

Capabilities

skills was renamed/reframed as governed capabilities.

Capabilities are governed executable/action surfaces usable by agents, operators, runtime/system components, and future external integrations such as MCP and web/search capability adapters.

Capabilities are not permissions, entitlements, provider ownership, or raw tool calls.

.agents

.agents is the repository meta-instruction surface for coding agents.

It is not the runtime src/agents plane.

Forbidden Current Paths

The current layout must not recreate:

agents/
analytics/
case/
control/
flow/
governance/
identity/
knowledge/
lineage/
llm/
models/
orchestration/
providers/
runtime/
skills/
capabilities/
state/
memory/

src/identity
src/skills
src/flow
src/knowledge/lineage

include/identity
include/skills
include/flow
include/yai/identity
include/yai/skills
include/yai/flow
include/yai/knowledge/lineage

protocols/topology
protocols/naming
protocols/ontology
protocols/system

Documentation/operator

These names are intentionally listed here as forbidden examples. They are not current canonical layout claims.

Validation Passed

The ROOT cutover stack has passed:

git diff --check
git diff --cached --check
make info
make yai
make -B yai
make validate-contract
protocol JSON validation
root forbidden dir guard
source/header canonical guards
direct include folder guard
protocol direct-child guard
include stale-prefix scans
live path residue scans
current docs stale-path scans
forbidden documentation primary-section guard
symlink scan
artifact/cache scan

Deferred Work

The ROOT cutover does not complete:

  • API/SDK/Web vocabulary alignment
  • yai_skill_* / YAI_SKILL_* lexical/API drain
  • serialized "skill" vocabulary migration
  • yai_identity_* / YAI_IDENTITY_* lexical/API drain
  • serialized "identity" vocabulary migration
  • yai_flow_* / yai_orchestration_* lexical/API drain
  • cross-repo API/SDK/Web vocabulary migration
  • physical memory extraction

memory is registered as a native plane direction, but physical extraction remains deferred.

Commit / Stack Notes

Baseline before the current uncommitted stack:

cffb318b9 Refactor root source layout and protocol planes

At the time this record was created, ROOT.4D through ROOT.8 remained in the current uncommitted stack.

Related Wave Reports

Documentation/internal/architecture/runtime/waves/root-source-cutover/root-0-preflight-inventory.md
Documentation/internal/architecture/runtime/waves/root-source-cutover/root-1-source-plane-physical-cutover.md
Documentation/internal/architecture/runtime/waves/root-source-cutover/root-2-header-namespace-and-agents-verticalization.md
Documentation/internal/architecture/runtime/waves/root-source-cutover/root-3-build-test-tool-path-realignment.md
Documentation/internal/architecture/runtime/waves/root-source-cutover/root-4-protocol-surface-normalization.md
Documentation/internal/architecture/runtime/waves/root-source-cutover/root-4b-lineage-orchestrator-workflow-correction.md
Documentation/internal/architecture/runtime/waves/root-source-cutover/root-4c-protocol-finalization-lineage-orchestrator.md
Documentation/internal/architecture/runtime/waves/root-source-cutover/root-4d-identity-demotion-runtime-access-boundary.md
Documentation/internal/architecture/runtime/waves/root-source-cutover/root-4e-skills-to-governed-capabilities-layer.md
Documentation/internal/architecture/runtime/waves/root-source-cutover/root-4f-cutover-stack-consolidation-live-residue-guard.md
Documentation/internal/architecture/runtime/waves/root-source-cutover/root-5-documentation-current-path-realignment.md
Documentation/internal/architecture/runtime/waves/root-source-cutover/root-6-root-cleanup-forbidden-stub-removal.md
Documentation/internal/architecture/runtime/waves/root-source-cutover/root-7-full-validation.md