diff --git a/docs/architecture/cognitive-evolution-control.md b/docs/architecture/cognitive-evolution-control.md index 90e88d0..d4fe8de 100644 --- a/docs/architecture/cognitive-evolution-control.md +++ b/docs/architecture/cognitive-evolution-control.md @@ -33,20 +33,37 @@ Evolution coordination is part of orchestration. GNUS-NEO-SWARM provides the pri ## Qualified Cognitive Event -A Qualified Cognitive Event is a versioned Cognitive Asset that records enough information to support later evaluation, replay, adaptation, and promotion. +A Qualified Cognitive Event is a versioned Cognitive Asset that records enough information to support later evaluation, replay, adaptation, and promotion. Its signed envelope also carries the effective governance derived from the request, tenant, and every referenced source asset. ```json { + "schema_version": "gcs.qualified-cognitive-event.v1", "event_id": "uuid", "request_id": "uuid", "session_id": "optional_uuid", "event_type": "memory|transition|routing|verification|arbitration|tool|training|benchmark", "source_assets": ["asset_id"], + "source_policy_hashes": ["policy_hash"], "model_and_expert_versions": ["version_or_cid"], - "policy_hash": "policy_hash", - "tenant_scope": "scope", - "privacy_scope": "scope", - "training_policy": "policy", + "policy_hash": "effective_policy_hash", + "tenant_scope": "optional_tenant_id", + "owner_id": "optional_owner_id", + "creator": "user|model|expert|tool|system|swarm", + "source_node": "node_id", + "privacy_scope": "local_only|user_private|trusted_devices|enterprise_private|tenant_private|shared|public", + "allowed_principals": ["principal_id"], + "allowed_roles": ["role_id"], + "replication_policy": "none|trusted_devices|private_subnet|tenant_nodes|public_swarm", + "inference_policy": "local_only|private_nodes|public_with_redaction|public_allowed", + "training_policy": "prohibited|local_only|tenant_only|anonymized_opt_in|allowed", + "export_policy": "prohibited|approval_required|allowed", + "retention_policy": "policy_or_reference", + "policy_tags": ["tag"], + "provenance": { + "derived_from": ["asset_id"], + "execution_claims": ["asset_id"], + "verification_results": ["asset_id"] + }, "outcome": "structured_outcome", "scores": { "confidence": 0.0, @@ -56,19 +73,39 @@ A Qualified Cognitive Event is a versioned Cognitive Asset that records enough i "user_feedback": 0.0 }, "created_at": 0, - "signature": "optional_signature" + "signing_identity": "node_or_service_id", + "signature": "signature_over_canonical_event" } ``` The event may reference existing Cognitive Assets rather than duplicating large prompts, traces, tool outputs, or model artifacts. +### Schema and Signature Contract + +`schema_version` is required and forms part of the signed canonical event. The major version identifies the decoding and validation contract; minor-compatible extensions may add optional fields while preserving the meaning of existing fields. Stored and replayed events retain the schema version under which they were created. + +The signature covers the canonical event envelope, including its schema version, source references, source policy hashes, effective policy hash, governance fields, outcome, scores, component versions, and provenance. This lets every receiving subsystem verify both event integrity and the policy context under which the event may be used. + +### Governance Resolution + +Qualified Cognitive Events inherit the governance of their source Cognitive Assets. Before dispatch, the RuntimeCoordinator or its attached policy service resolves the referenced assets and computes one effective governance envelope: + +- `allowed_principals` and `allowed_roles` are the intersection of the applicable source, request, tenant, and deployment permissions; +- privacy, replication, inference, training, and export permissions use the most restrictive applicable scope; +- retention follows the earliest applicable expiry or the strictest governing retention rule; +- policy tags and provenance references are preserved across derivation; +- `source_policy_hashes` bind the event to the policies resolved from its sources; +- `policy_hash` identifies the resulting effective governance used for dispatch. + +A derived event therefore remains within the same or a narrower authorization boundary than its sources. Receiving subsystems verify the schema, signature, effective policy, and source-policy linkage before using the event for memory, replay, adaptation, replication, export, or training. + ## Coordination Flow 1. The RuntimeCoordinator completes the normal request path. 2. Existing subsystems emit structured Cognitive Assets and outcome signals. 3. The coordinator or an attached policy service assembles Qualified Cognitive Events. -4. Privacy, authorization, retention, replication, and training policies are applied before any adaptation path receives the event. -5. The event is routed to one or more existing adaptive targets: +4. Source assets are resolved, their governance is combined into the effective policy envelope, and the canonical event is signed before adaptation dispatch. +5. The event is routed to one or more existing adaptive targets within that effective governance: - GAML write evaluation; - Objective Memory / VTG edge and ranking updates; - routing, planning, verifier, critic, or arbitration tuning; @@ -83,12 +120,13 @@ The event may reference existing Cognitive Assets rather than duplicating large All adaptive paths should accept a common event envelope with: -- request, session, tenant, and policy identity; -- source Cognitive Asset references; +- signed schema version and canonical event identity; +- request, session, tenant, owner, and policy identity; +- source Cognitive Asset and source-policy references; +- effective privacy, authorization, replication, inference, training, export, and retention governance; - component and artifact versions; - structured outcomes and reward signals; -- privacy, inference, training, export, and retention policy; -- provenance and signatures where required. +- provenance and signatures. Subsystem-specific payloads remain allowed. VTG transition outcomes, EGGROLL fitness packets, Cognitive Training Events, verifier results, and benchmark results may keep their specialized fields while sharing the common envelope. @@ -96,6 +134,7 @@ Subsystem-specific payloads remain allowed. VTG transition outcomes, EGGROLL fit A replayable event should identify: +- the Qualified Cognitive Event schema version and effective policy hash; - the execution plan or plan reference; - model, expert, adapter, tokenizer, quantization, and runtime versions; - context packet and policy hashes; @@ -103,7 +142,7 @@ A replayable event should identify: - deterministic seeds or execution class where available; - expected validators and measurable outcome criteria. -Replay uses the public GCS request and event contracts. It may execute locally, through SGProcessingManager workloads, or through SuperGenius distributed execution under the existing runtime ownership rules. +Replay uses the public GCS request and event contracts. It may execute locally, through SGProcessingManager workloads, or through SuperGenius distributed execution under the existing runtime ownership rules and the event's effective governance. ### Promotion Contract @@ -151,4 +190,4 @@ Raw hidden reasoning and restricted source material remain governed by the exist ## Summary -Cognitive Evolution Coordination gives GCS one structured path from completed work to memory, transition, policy, and model improvement. It unifies existing learning mechanisms through shared event, replay, and promotion contracts while preserving the current RuntimeCoordinator, component ownership, security, memory, VTG, and EGGROLL architecture. +Cognitive Evolution Coordination gives GCS one structured path from completed work to memory, transition, policy, and model improvement. It unifies existing learning mechanisms through signed, governed event, replay, and promotion contracts while preserving the current RuntimeCoordinator, component ownership, security, memory, VTG, and EGGROLL architecture. diff --git a/llms-meta.json b/llms-meta.json index 40ceea7..e1b2470 100644 --- a/llms-meta.json +++ b/llms-meta.json @@ -3537,7 +3537,7 @@ "nav_section": "**Genius Cognitive System Architecture Documentation**" }, "docs:./system-overview.md": { - "hash": "855d5a3c8d7cb78d", + "hash": "39532c9af26efa38", "description": "Answers what the layered pipeline looks like from client API through router, memory, execution, verification, grounding, and final response.", "category": "architecture", "optional": false, @@ -3641,7 +3641,7 @@ "nav_section": "**Genius Cognitive System Architecture Documentation**" }, "docs:./cognitive-retaining-system.md": { - "hash": "c1c2bbee833279ee", + "hash": "5b1041a1afb7a8a9", "description": "Answers how targeted retraining enables continuous lightweight adaptation of user/role-specific cognition via adapters, routing weights, and critic weights without full model retraining.", "category": "architecture", "optional": false, @@ -3735,6 +3735,14 @@ "optional": false, "exclude": false, "nav_section": "**Genius Cognitive System Architecture Documentation**" + }, + "docs:./cognitive-evolution-control.md": { + "hash": "f27594d3fc0c77c7", + "description": "Answers how GCS turns qualified cognitive events into governed memory, transition, routing, arbitration, benchmark, and EGGROLL adaptation workflows through shared replay and promotion contracts.", + "category": "architecture", + "optional": false, + "exclude": false, + "nav_section": "**Genius Cognitive System Architecture Documentation**" } } }