7f56ca4d46
12 council design briefs for distributed OS specification project targeting 1024-node Hopper/Grace/Blackwell GPU cluster with Weka parallel filesystem. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
545 lines
40 KiB
Markdown
545 lines
40 KiB
Markdown
# Council Design Brief: Inter-Council Synthesis
|
||
|
||
**Council ID:** `council-synth`
|
||
**Mission:** Maintain the architectural coherence of DistOS as a whole. This council does not own any subsystem. Instead, it owns the space between subsystems — the interface contracts, the dependency graph, the consistency of cross-cutting assumptions, and the resolution of conflicts between councils that cannot resolve their differences independently. When the DistOS specification is complete, `council-synth` must be able to certify that every decision made by every council is compatible with every decision made by every other council.
|
||
**UCXL Base Address:** `ucxl://council-synth:*@DistOS:integration/*`
|
||
**Agent Count:** ~100
|
||
**Status:** Design Brief — Constitution Phase
|
||
|
||
---
|
||
|
||
## 1. Scope and Responsibilities
|
||
|
||
`council-synth` is unique among all DistOS councils: it has no subsystem of its own to design. Its authority is horizontal rather than vertical. Specifically:
|
||
|
||
1. **Monitor Decision Records from all councils via UCXL subscription.** Every DR published by any council is read by `council-synth` Conflict Detectors within hours of publication. No council's decisions are exempt from synthesis review.
|
||
|
||
2. **Detect conflicts between council decisions.** The canonical example: `council-sched` assumes a shared global memory space for scheduling state, but `council-mem` has chosen a message-passing-only inter-node memory model. This conflict is invisible to both councils independently; `council-synth` makes it visible.
|
||
|
||
3. **Convene cross-council mini-councils to resolve conflicts.** When a conflict is detected, the Lead Synthesiser convenes a focused session with representatives from the affected councils, facilitated by an Arbitrator agent. The mini-council produces a resolution DR that updates the affected specs.
|
||
|
||
4. **Maintain the Global Architectural Coherence Document (GACD).** A living document that describes the whole-system architecture as currently understood — the subsystems, their interfaces, their shared assumptions, and the status of each assumption (agreed, under review, contested). This is the primary artefact that a human reviewer can consult to understand the state of the DistOS design.
|
||
|
||
5. **Manage the dependency graph between all councils.** Which councils must complete which deliverables before which other councils can proceed? `council-synth` maintains this graph, flags blocked councils, and escalates to `council-meta` when a blockage threatens the project timeline.
|
||
|
||
6. **Arbitrate when two councils have incompatible requirements.** Some conflicts cannot be resolved by the affected councils alone — they represent genuine trade-offs with no obvious correct answer. In these cases, `council-synth` Arbitrators make a binding recommendation (subject to appeal to `council-meta`) based on the ATAM methodology and the Project Constitution's guiding principles.
|
||
|
||
7. **Allocate the global performance budget.** The DistOS specification must include quantitative performance targets (latency, throughput, jitter) for the 1024-node cluster. These targets cannot be set by individual subsystems independently — a scheduler that claims 10 microsecond dispatch latency, a memory system that claims 1 microsecond allocation, and a network stack that claims 5 microsecond RPC round-trip imply a composed system latency budget that may or may not be consistent with the target hardware. `council-synth` owns this budget and allocates it across subsystems.
|
||
|
||
8. **Verify consistency model alignment.** The memory model chosen by `council-mem`, the failure model chosen by `council-fault`, and the network guarantees provided by `council-net` must all agree on the consistency model they collectively provide to `council-api`'s system call interface. This alignment is `council-synth`'s most technically demanding task.
|
||
|
||
9. **Manage evolutionary architecture.** The DistOS specification is not a static document to be sealed at the end of 14 days. It must be designed to evolve. `council-synth` specifies the evolution policy: how new subsystems are added, how interfaces are changed, and how the coherence invariants are maintained as the spec evolves post-delivery.
|
||
|
||
`council-synth` does **not** own: the design of any subsystem; formal verification (owned by `council-verify`); the narrative documentation (owned by `council-docs` and `council-arch`); adversarial testing (owned by `council-qa`).
|
||
|
||
---
|
||
|
||
## 2. Research Domains
|
||
|
||
### 2.1 Architecture Trade-off Analysis Method (ATAM)
|
||
|
||
ATAM (Bass, Clements, and Kazman, 2003) is the systematic methodology for evaluating software architectures against quality attribute requirements. It was developed at the SEI and has been validated in large-scale industrial deployments.
|
||
|
||
The ATAM process:
|
||
1. Present the architecture: stakeholders and architects explain the design
|
||
2. Identify quality attribute scenarios: concrete, measurable instances of quality attributes (e.g., "under a 10% node failure rate, no job should wait more than 5 seconds for rescheduling")
|
||
3. Identify architectural approaches: which architectural decisions (style, pattern, tactic) address each scenario
|
||
4. Generate the utility tree: a structured decomposition of quality attributes, sub-attributes, and prioritised scenarios
|
||
5. Analyse architectural approaches: for each approach, identify sensitivity points (design decisions that materially affect the quality attribute), trade-off points (decisions that affect two or more quality attributes in tension), and risks
|
||
6. Identify risks and non-risks: document architectural decisions that carry risk and those that are well-understood
|
||
|
||
`council-synth` Trade-off Analysts are required to be proficient in ATAM. Every major cross-council conflict will be analysed using the ATAM utility tree methodology.
|
||
|
||
Key references:
|
||
- Bass, L., Clements, P., and Kazman, R. *Software Architecture in Practice* (3rd ed., 2012). Addison-Wesley. Chapters 14–16 on ATAM.
|
||
- Kazman, R. et al. "ATAM: Method for Architecture Evaluation." *CMU/SEI-2000-TR-004*. 2000. The primary technical report on ATAM methodology.
|
||
- Clements, P. et al. *Documenting Software Architectures: Views and Beyond* (2nd ed., 2010). Addison-Wesley. The companion to ATAM on how to document architecture decisions.
|
||
|
||
### 2.2 Conflict Detection in Distributed Design Processes
|
||
|
||
Detecting incompatible assumptions across independent design teams is a known research problem. The primary approaches are:
|
||
|
||
- **Assumption surfacing:** Each council explicitly documents its assumptions about the environment its subsystem operates in. `council-synth` collects these assumption lists and checks them for mutual inconsistency.
|
||
- **Interface contract comparison:** Each council publishes the interface it expects to consume and the interface it promises to provide. `council-synth` checks that every consumed interface is covered by some council's provided interface, and that the specifications are compatible.
|
||
- **Design decision dependency tracking:** Design decisions have dependencies — a choice made by one council constrains the options available to another. `council-synth` maintains a dependency graph where nodes are design decisions and edges represent constraints.
|
||
|
||
Key references:
|
||
- Nuseibeh, B. et al. "A Framework for Expressing the Relationships Between Multiple Views in Requirements Specification." *IEEE Transactions on Software Engineering* 20(10), 1994. The foundational work on multi-view consistency checking.
|
||
- van Lamsweerde, A. and Willemet, L. "Inferring Declarative Requirements Specifications from Operational Scenarios." *IEEE Transactions on Software Engineering* 24(12), 1998.
|
||
- Garlan, D. et al. "Architectural Mismatch: Why Reuse Is So Hard." *IEEE Software* 12(6), 1995. Introduces the concept of architectural mismatch — what happens when independently designed components make incompatible assumptions. This paper names the core problem that `council-synth` exists to solve.
|
||
|
||
### 2.3 Dependency Graph Management
|
||
|
||
The DistOS project has approximately 12 councils, each producing dozens of deliverables, with complex inter-dependencies. Managing this graph requires:
|
||
|
||
- A machine-readable dependency graph format (likely a directed acyclic graph where nodes are deliverables and edges are "depends on" relationships)
|
||
- Cycle detection (circular dependencies must be identified and broken)
|
||
- Critical path analysis (which chain of dependencies determines the minimum project duration?)
|
||
- Blockage detection (which deliverables are currently unmet and which councils are blocked as a result?)
|
||
|
||
Key references:
|
||
- Cormen, T. et al. *Introduction to Algorithms* (4th ed., 2022). MIT Press. Chapter 22 on graph algorithms: topological sort, strongly connected components, DAG shortest paths.
|
||
- Brooks, F. *The Mythical Man-Month* (1995 anniversary edition). Addison-Wesley. The dependency management lessons here, while not formal, are empirically grounded and must inform how `council-synth` manages blockages.
|
||
- Reinertsen, D. *The Principles of Product Development Flow* (2009). Celeritas. Chapter 3 on queuing theory and dependency cost. Useful for quantifying the cost of blocked councils.
|
||
|
||
### 2.4 Interface Contract Enforcement
|
||
|
||
An interface contract specifies what a consumer may expect from a provider. In a distributed OS context:
|
||
- **Pre-conditions:** what must be true before a call is made
|
||
- **Post-conditions:** what is guaranteed to be true after a call returns successfully
|
||
- **Invariants:** what must remain true across all states
|
||
- **Error contracts:** which error conditions the provider guarantees to detect and report
|
||
|
||
`council-synth` Interface Contract Enforcement is the process of verifying that every interface between subsystems has a formal contract (supplied by `council-api` in Alloy-checkable form) and that no council's spec violates the contract it has agreed to.
|
||
|
||
Key references:
|
||
- Meyer, B. *Object-Oriented Software Construction* (2nd ed., 1997). Prentice Hall. Chapter 11 on Design by Contract. The foundational text.
|
||
- Leavens, G. and Sitaraman, M. (eds.) *Foundations of Component-Based Systems*. 2000. Cambridge University Press. Chapter on behavioural contracts and compatibility.
|
||
- Hatcliff, J. et al. "Behavioral Interface Specification Languages." *ACM Computing Surveys* 44(3), 2012.
|
||
|
||
### 2.5 Performance Budget Allocation
|
||
|
||
Allocating latency and throughput budgets across subsystems in a system with tight end-to-end requirements requires queuing theory and performance modelling:
|
||
|
||
- **Amdahl's Law:** The speedup from improving a component is bounded by the fraction of time spent in that component. Subsystems that are rarely on the critical path do not benefit from tight latency budgets.
|
||
- **Little's Law:** In a stable queuing system, L = λW (average queue length = arrival rate × average wait time). Used to reason about throughput and latency trade-offs in the scheduler and network stack.
|
||
- **Tail latency management:** At 1024 nodes, the 99th-percentile latency of any distributed operation is the primary engineering challenge. The Tail at Scale (Dean and Barroso, 2013) is mandatory reading.
|
||
- **Latency budget decomposition:** If the end-to-end target is 100 microseconds for a distributed system call, how many microseconds are allocated to: kernel entry, capability check, network transmission, remote kernel entry, computation, response, network return? This decomposition is `council-synth`'s responsibility.
|
||
|
||
Key references:
|
||
- Dean, J. and Barroso, L. "The Tail at Scale." *Communications of the ACM* 56(2), 2013. Demonstrates that at large scale, tail latency dominates user-visible performance. Introduces hedged requests and tied requests as mitigation strategies. Mandatory reading.
|
||
- Barroso, L., Clidaras, J., and Holzle, U. *The Datacenter as a Computer* (3rd ed., 2018). Morgan and Claypool. Chapter 5 on latency budget analysis in warehouse-scale systems.
|
||
- Jain, R. *The Art of Computer Systems Performance Analysis* (1991). Wiley. Chapters 28–30 on queuing networks and latency decomposition.
|
||
- Leverich, J. and Kozyrakis, C. "Reconciling High Server Utilization and Sub-Millisecond Quality-of-Service." *EuroSys 2014*. Directly relevant to the latency vs. utilisation trade-off in the scheduler.
|
||
|
||
### 2.6 Consistency Model Alignment
|
||
|
||
The most technically complex task for `council-synth` is ensuring that the consistency models chosen by `council-mem`, `council-net`, and `council-fault` are mutually compatible and that the composed model matches what `council-api` has promised to applications.
|
||
|
||
The consistency model stack:
|
||
- `council-mem` chooses a hardware-level memory consistency model for GPU operations (likely release-acquire, matching Hopper/Blackwell)
|
||
- `council-net` chooses a network-level consistency model for distributed operations (likely causal consistency or linearisability for control plane, eventual consistency for data plane)
|
||
- `council-fault` chooses a consistency model for state that survives node failures (determined by the consensus protocol choice)
|
||
- `council-api` promises applications a composed consistency model
|
||
|
||
If these choices are incompatible — for example, if the application API promises linearisability but the network stack only provides causal consistency — the system is unsound. `council-synth` must detect this and convene a resolution mini-council.
|
||
|
||
Key references:
|
||
- Herlihy, M. and Wing, J. "Linearizability: A Correctness Condition for Concurrent Objects." *JACM* 37(3), 1990. (Cited in `council-verify` brief; essential here too.)
|
||
- Bailis, P. et al. "Highly Available Transactions: Virtues and Limitations." *VLDB 2014*. Proves which consistency models are achievable without sacrificing availability (CAP theorem refinement). Directly constrains what `council-fault` can promise to `council-api`.
|
||
- Bailis, P. and Ghodsi, A. "Eventual Consistency Today: Limitations, Extensions, and Beyond." *ACM Queue* 11(3), 2013.
|
||
- Brewer, E. "CAP Twelve Years Later: How the 'Rules' Have Changed." *IEEE Computer* 45(2), 2012. Brewer's own retrospective on CAP, which is more nuanced than the original conjecture. Required for understanding the actual trade-off space.
|
||
- Crooks, N. et al. "Seeing is Believing: A Client-Centric Isolation Definition for Databases." *SIGMOD 2017*. Client-centric consistency definitions that map to what an application developer actually observes.
|
||
|
||
### 2.7 Resource Contention Arbitration
|
||
|
||
Multiple subsystems compete for shared physical resources: CPU cycles, GPU memory bandwidth, NVLink bandwidth, Weka FS I/O bandwidth, and DRAM. `council-synth` must establish a policy for how these contentions are resolved when subsystem specs make conflicting demands on the same resource.
|
||
|
||
Key references:
|
||
- Zaharia, M. et al. "Improving MapReduce Performance in Heterogeneous Environments." *OSDI 2008*. Speculative execution and heterogeneity-aware scheduling; relevant to scheduler-network resource contention.
|
||
- Delimitrou, C. and Kozyrakis, C. "Paragon: QoS-Aware Scheduling for Heterogeneous Datacenters." *ASPLOS 2013*. QoS-aware scheduling as a framework for resource contention arbitration.
|
||
- Grandl, R. et al. "Multi-Resource Packing for Cluster Schedulers." *SIGCOMM 2014*. Resource packing across multiple resource dimensions (CPU, memory, network, GPU) — the exact problem for the 1024-node cluster.
|
||
|
||
### 2.8 Evolutionary Architecture
|
||
|
||
The DistOS specification will evolve after Day 14. `council-synth` must specify how:
|
||
|
||
- New subsystems are added without breaking existing subsystem interfaces
|
||
- Interface contracts are changed with defined compatibility guarantees
|
||
- Architectural decisions are revisited (when is it permissible to reverse a previously made decision, and what is the process?)
|
||
- The coherence invariants are maintained as new agents join and contribute
|
||
|
||
Key references:
|
||
- Ford, N. et al. *Building Evolutionary Architectures* (2nd ed., 2022). O'Reilly. The definitive treatment of architecture that supports guided change. Chapter 3 on fitness functions — automated checks that verify architectural properties — is directly applicable to UCXL-based coherence monitoring.
|
||
- Garlan, D. and Perry, D. "Introduction to the Special Issue on Software Architecture." *IEEE Transactions on Software Engineering* 21(4), 1995.
|
||
- Fowler, M. *Patterns of Enterprise Application Architecture* (2002). Addison-Wesley. Chapter on evolving architectures.
|
||
- Nadareishvili, I. et al. *Microservice Architecture* (2016). O'Reilly. Chapter 4 on evolutionary API design patterns.
|
||
|
||
### 2.9 ATAM Applied to Distributed OS Design
|
||
|
||
While ATAM was developed for traditional software architectures, it applies to distributed OS design with some adaptations:
|
||
|
||
- **Quality attributes for a distributed OS:** performance (latency, throughput, tail latency), reliability (MTBF, MTTR, availability under f failures), security (isolation strength, attack surface), maintainability (spec complexity, evolvability), and developer experience (API ergonomics, debuggability)
|
||
- **Utility tree for DistOS:** `council-synth` must construct and maintain the DistOS utility tree mapping quality attribute scenarios to architectural decisions
|
||
- **Sensitivity and trade-off points:** the ATAM outputs that are most valuable to `council-synth` — decisions that are tightly coupled to quality attributes (sensitivity points) and decisions where optimising for one attribute degrades another (trade-off points)
|
||
|
||
Key examples of trade-off points expected in DistOS:
|
||
- **Linearisability vs. availability:** Making all distributed operations linearisable (strongest consistency) requires coordination that reduces availability under network partitions (CAP constraint).
|
||
- **Memory coherence vs. bandwidth:** Maintaining fine-grained cache coherence across 1024 nodes provides stronger consistency guarantees but consumes NVLink bandwidth for coherence traffic.
|
||
- **POSIX compatibility vs. API ergonomics:** Supporting the POSIX shim layer adds complexity and performance overhead to the clean-slate API.
|
||
- **Formal verification completeness vs. project timeline:** Fully verifying every subsystem spec in 14 days may not be feasible; some subsystems may require deferring full verification.
|
||
|
||
---
|
||
|
||
## 3. Agent Roles
|
||
|
||
| Role | Count | Responsibilities |
|
||
|------|-------|-----------------|
|
||
| Lead Synthesiser | 1 | Chairs all mini-councils; owns the GACD; reports to `council-meta`; makes binding arbitration recommendations; maintains the global UCXL subscription |
|
||
| Conflict Detectors | 30 | Monitor UCXL feeds from all councils; parse incoming DRs; identify potential conflicts; triage and escalate genuine conflicts to Lead Synthesiser |
|
||
| Trade-off Analysts | 30 | Apply ATAM methodology to evaluate conflict resolution alternatives; construct utility tree entries for cross-cutting decisions; produce trade-off analysis reports |
|
||
| Arbitrators | 20 | Facilitate mini-council sessions; ensure both sides are heard; produce resolution DRs; track resolution implementation |
|
||
| Coherence Auditors | 19 | Verify global consistency: interface contracts are satisfied, consistency models are aligned, performance budget is respected, dependency graph is acyclic |
|
||
|
||
**Total:** 100 agents
|
||
|
||
---
|
||
|
||
## 4. Key Deliverables
|
||
|
||
All artifacts use the pattern `ucxl://council-synth:{role}@DistOS:integration/^^/{artifact-type}/{name}`.
|
||
|
||
### 4.1 Global Architectural Coherence Document (GACD)
|
||
|
||
The living document describing the whole-system architecture as currently agreed. Updated continuously throughout the project.
|
||
|
||
```
|
||
ucxl://council-synth:lead-synthesiser@DistOS:integration/^^/docs/global-architectural-coherence.md
|
||
```
|
||
|
||
### 4.2 Conflict Registry
|
||
|
||
A machine-readable log of all detected conflicts, their status (open, in-resolution, resolved, deferred), the councils involved, and the UCXL address of the resolution DR.
|
||
|
||
```
|
||
ucxl://council-synth:conflict-detector@DistOS:integration/^^/registries/conflict-registry.json
|
||
```
|
||
|
||
### 4.3 Dependency Graph
|
||
|
||
A machine-readable directed acyclic graph of all council deliverable dependencies. Updated as deliverables are published and consumed. Rendered as a human-readable diagram for `council-meta` and project stakeholders.
|
||
|
||
```
|
||
ucxl://council-synth:coherence-auditor@DistOS:integration/^^/graphs/dependency-graph.json
|
||
ucxl://council-synth:coherence-auditor@DistOS:integration/^^/graphs/dependency-graph.svg
|
||
```
|
||
|
||
### 4.4 Performance Budget Allocation Document
|
||
|
||
The authoritative record of latency and throughput budget allocations across all subsystems.
|
||
|
||
```
|
||
ucxl://council-synth:trade-off-analyst@DistOS:integration/^^/docs/performance-budget.md
|
||
```
|
||
|
||
### 4.5 Consistency Model Alignment Report
|
||
|
||
Documents the agreed consistency model stack: hardware-level (memory), network-level (net), fault-tolerant (fault), and application-visible (api). Confirms they are mutually compatible or records the accepted trade-off.
|
||
|
||
```
|
||
ucxl://council-synth:coherence-auditor@DistOS:integration/^^/reports/consistency-model-alignment.md
|
||
```
|
||
|
||
### 4.6 Resolution Decision Records
|
||
|
||
One DR per resolved conflict. Each DR includes: the conflict description, the councils involved, the alternatives evaluated (ATAM analysis), the decision reached, the rationale, and the spec changes required.
|
||
|
||
```
|
||
ucxl://council-synth:arbitrator@DistOS:integration/^^/decisions/conflict-{id}-resolution.md
|
||
```
|
||
|
||
Example:
|
||
|
||
```
|
||
ucxl://council-synth:arbitrator@DistOS:integration/^^/decisions/conflict-001-sched-vs-mem-memory-model.md
|
||
ucxl://council-synth:arbitrator@DistOS:integration/^^/decisions/conflict-002-net-vs-fault-consistency.md
|
||
```
|
||
|
||
### 4.7 ATAM Utility Tree
|
||
|
||
The structured decomposition of DistOS quality attribute scenarios, architectural approaches, sensitivity points, and trade-off points.
|
||
|
||
```
|
||
ucxl://council-synth:trade-off-analyst@DistOS:integration/^^/docs/atam-utility-tree.md
|
||
```
|
||
|
||
### 4.8 Interface Contract Registry
|
||
|
||
A registry of all inter-subsystem interface contracts: which council provides what interface, which council consumes it, the contract's UCXL address, and its verification status.
|
||
|
||
```
|
||
ucxl://council-synth:coherence-auditor@DistOS:integration/^^/registries/interface-contract-registry.json
|
||
```
|
||
|
||
### 4.9 Evolutionary Architecture Policy
|
||
|
||
The specification of how DistOS can evolve post-delivery while maintaining coherence.
|
||
|
||
```
|
||
ucxl://council-synth:lead-synthesiser@DistOS:integration/^^/policies/evolutionary-architecture.md
|
||
```
|
||
|
||
### 4.10 Synthesis Final Report
|
||
|
||
The end-of-project coherence certification document. States that all detected conflicts are resolved or explicitly deferred with risk assessment, all interface contracts are satisfied, the consistency model is aligned, and the performance budget is consistent.
|
||
|
||
```
|
||
ucxl://council-synth:lead-synthesiser@DistOS:integration/^^/reports/synthesis-final-report.md
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Decision Points
|
||
|
||
All DRs use the address pattern `ucxl://council-synth:lead-synthesiser@DistOS:integration/^^/decisions/{dr-id}.md`.
|
||
|
||
### DP-S01: Consistency Model for the Application-Visible API
|
||
|
||
This is the most consequential decision in the entire DistOS project. It determines what `council-api` can promise to applications, which in turn constrains what `council-mem`, `council-net`, and `council-fault` must deliver. The options are:
|
||
|
||
- **Linearisability everywhere:** Strongest guarantee, highest cost. Requires global coordination for every distributed operation. Not recommended for the data plane; may be appropriate for the control plane.
|
||
- **Linearisability for control, causal for data:** A two-tier model. Control-plane operations (node management, job submission, lock acquisition) are linearisable. Data-plane operations (tensor reads/writes, streaming I/O) are causally consistent. This is the recommended starting position.
|
||
- **Per-operation consistency annotation:** Applications declare the consistency level required per operation. Maximum flexibility, maximum complexity, highest risk of programmer error.
|
||
|
||
**Deciding parties:** Lead Synthesiser, `council-mem`, `council-net`, `council-fault`, `council-api`, Trade-off Analysts
|
||
|
||
### DP-S02: Performance Budget Top-Level Allocation
|
||
|
||
Establish the top-level latency targets that subsystem budgets are derived from. Candidate targets for a 1024-node Hopper/Blackwell cluster:
|
||
|
||
| Operation | Target P50 | Target P99 |
|
||
|-----------|-----------|-----------|
|
||
| Local GPU kernel launch | 2 μs | 10 μs |
|
||
| GPU memory allocation | 5 μs | 50 μs |
|
||
| Node-local system call round-trip | 1 μs | 5 μs |
|
||
| Distributed RPC (same rack) | 10 μs | 100 μs |
|
||
| Distributed RPC (cross-rack) | 50 μs | 500 μs |
|
||
| Consensus write (Raft/Paxos) | 500 μs | 5 ms |
|
||
| Collective AllReduce (1024 nodes) | 1 ms | 10 ms |
|
||
|
||
These numbers must be validated against the known hardware capabilities of the target cluster (Hopper NVLink 4.0 bandwidth, InfiniBand HDR 200 Gbps, Weka FS parallel I/O) and then allocated to subsystems.
|
||
|
||
**Deciding parties:** Lead Synthesiser, Trade-off Analysts, `council-sched`, `council-mem`, `council-net`
|
||
|
||
### DP-S03: Conflict Escalation Policy
|
||
|
||
Define the escalation path when `council-synth` and the affected councils cannot reach agreement in a mini-council. Options: (a) Lead Synthesiser makes a binding ruling, (b) escalate to `council-meta` for project-level arbitration, (c) put the conflict to a vote of all council leads. A clear escalation policy is essential to prevent deadlocked conflicts from blocking the project timeline.
|
||
**Deciding parties:** Lead Synthesiser, `council-meta`
|
||
|
||
### DP-S04: Global UCXL Subscription Architecture
|
||
|
||
`council-synth` Conflict Detectors must monitor DR feeds from 11 other councils simultaneously. Define the UCXL subscription topology: (a) each Conflict Detector subscribes to a subset of councils (partitioned), (b) all Conflict Detectors subscribe to all councils with deduplication (redundant, robust), or (c) a tiered model with dedicated detectors per council that escalate to a shared pool. The choice affects latency to detection and resilience to Conflict Detector failures.
|
||
**Deciding parties:** Lead Synthesiser, Coherence Auditors
|
||
|
||
### DP-S05: Architectural Fitness Functions
|
||
|
||
Following Ford et al. (Building Evolutionary Architectures), define at least five automated fitness functions — machine-checkable assertions about the DistOS architecture — that can be run continuously to verify that the architecture remains coherent as it evolves. Examples:
|
||
|
||
- No interface contract is consumed without a published provider
|
||
- No performance budget allocation exceeds the top-level target
|
||
- Every DR cites at least one research reference
|
||
- No cycle exists in the dependency graph
|
||
- Every public system call has an Alloy-verified interface contract
|
||
|
||
**Deciding parties:** Lead Synthesiser, Coherence Auditors, `council-verify`
|
||
|
||
---
|
||
|
||
## 6. Dependencies on Other Councils
|
||
|
||
`council-synth` is the most broadly dependent council in DistOS. It depends on all councils (as inputs to synthesis) and all councils depend on it (as the source of coherence directives and conflict resolutions).
|
||
|
||
| Council | Relationship | What council-synth consumes | What council-synth produces |
|
||
|---------|-------------|----------------------------|----------------------------|
|
||
| `council-sched` | Bidirectional | All DRs; scheduling assumptions; performance requirements | Conflict resolutions; performance budget allocation; coherence directives |
|
||
| `council-mem` | Bidirectional | Memory model choice; consistency model; Weka FS integration assumptions | Consistency model alignment ruling; coherence directives |
|
||
| `council-net` | Bidirectional | Network protocol choices; consistency guarantees; latency estimates | Consistency model alignment ruling; performance budget for network |
|
||
| `council-fault` | Bidirectional | Consensus protocol choice; failure model; recovery semantics | Coherence directives on fault/consistency interaction |
|
||
| `council-sec` | Bidirectional | Security model; isolation assumptions; capability model | Coherence directives on sec/API interaction |
|
||
| `council-telemetry` | Consuming | Metering model; performance overhead estimates | Performance budget for telemetry overhead |
|
||
| `council-verify` | Providing specifications to | Conflict resolution DRs; interface contract registry | Verification results that inform synthesis |
|
||
| `council-qa` | Consuming | Test failure reports that reveal architectural inconsistencies | Architectural issue reports for QA follow-up |
|
||
| `council-api` | Bidirectional | API philosophy decisions; consistency model promises to applications | Consistency model ruling; conflict resolutions affecting API |
|
||
| `council-docs` | Providing to | N/A | GACD sections for incorporation into final spec |
|
||
| `council-arch` | Providing to | N/A | Conflict registry and resolution DRs for archaeological narrative |
|
||
| `council-meta` | Reporting to | Project health directives; escalation rulings | Blocked council reports; synthesis status updates |
|
||
|
||
**Dependency inversion note:** `council-synth` must be operational and subscribed to all UCXL feeds before the other councils begin producing DRs. It is the first council to be fully formed and the last to be disbanded.
|
||
|
||
---
|
||
|
||
## 7. WHOOSH Configuration
|
||
|
||
### 7.1 Team Formation
|
||
|
||
```yaml
|
||
council_id: council-synth
|
||
display_name: "Inter-Council Synthesis Council"
|
||
target_size: 100
|
||
formation_strategy: competency_weighted
|
||
priority: critical # Must be formed before all other councils begin producing DRs
|
||
required_roles:
|
||
- role: lead-synthesiser
|
||
count: 1
|
||
persona: systems-analyst
|
||
competencies: [architectural-analysis, atam, distributed-systems, conflict-resolution, ucxl]
|
||
- role: conflict-detector
|
||
count: 30
|
||
persona: systems-analyst
|
||
competencies: [design-review, assumption-analysis, distributed-systems, dependency-tracking]
|
||
- role: trade-off-analyst
|
||
count: 30
|
||
persona: systems-analyst
|
||
competencies: [atam, performance-modelling, queuing-theory, cap-theorem, consistency-models]
|
||
- role: arbitrator
|
||
count: 20
|
||
persona: systems-analyst
|
||
competencies: [facilitation, conflict-resolution, decision-records, distributed-systems]
|
||
- role: coherence-auditor
|
||
count: 19
|
||
persona: systems-analyst
|
||
competencies: [interface-contracts, dependency-graphs, consistency-models, ucxl, fitness-functions]
|
||
```
|
||
|
||
### 7.2 Quorum Rules
|
||
|
||
```yaml
|
||
quorum:
|
||
decision_threshold: 0.6 # 60% of active agents for routine decisions
|
||
lead_synthesiser_binding: true # Lead Synthesiser's ruling is binding after mini-council process
|
||
arbitration_quorum: 3 # Minimum 3 Arbitrators must participate in any mini-council
|
||
conflict_detection_threshold: 1 # A single Conflict Detector raising a flag is sufficient to open a conflict
|
||
coherence_certification:
|
||
required_auditors: 5 # At least 5 Coherence Auditors must sign the final coherence certification
|
||
escalation_to_meta:
|
||
trigger: stalled_conflict # Conflict unresolved for more than 6 hours
|
||
target: council-meta
|
||
performance_budget_change:
|
||
threshold: 0.9 # 90% supermajority required to change top-level performance targets
|
||
required_councils: [council-sched, council-mem, council-net]
|
||
```
|
||
|
||
### 7.3 Subchannels
|
||
|
||
```yaml
|
||
subchannels:
|
||
- id: synth-all-council-dr-feed
|
||
subscribers: [conflict-detector]
|
||
purpose: "Real-time UCXL subscription to Decision Records from all councils. Primary input feed for conflict detection."
|
||
ucxl_feed: "ucxl://council-*:*@DistOS:*/^^/decisions/*"
|
||
delivery: streaming
|
||
priority: high
|
||
|
||
- id: synth-conflict-triage
|
||
subscribers: [conflict-detector, lead-synthesiser]
|
||
purpose: "Triage queue for potential conflicts. Conflict Detectors post candidates here for Lead Synthesiser review before a formal conflict is opened."
|
||
ucxl_feed: "ucxl://council-synth:conflict-detector@DistOS:integration/^^/triage/*"
|
||
|
||
- id: synth-mini-councils
|
||
subscribers: [lead-synthesiser, arbitrator, affected_council_representatives]
|
||
purpose: "Active mini-council sessions. Each conflict gets a dedicated ephemeral sub-thread here."
|
||
ucxl_feed: "ucxl://council-synth:arbitrator@DistOS:integration/^^/mini-councils/*"
|
||
membership: dynamic # Representatives from affected councils join per-conflict
|
||
|
||
- id: synth-tradeoff-analysis
|
||
subscribers: [trade-off-analyst, lead-synthesiser]
|
||
purpose: "ATAM utility tree construction and trade-off analysis. Trade-off Analysts post analyses here for Lead Synthesiser input to mini-councils."
|
||
ucxl_feed: "ucxl://council-synth:trade-off-analyst@DistOS:integration/^^/tradeoffs/*"
|
||
|
||
- id: synth-performance-budget
|
||
subscribers: [trade-off-analyst, coherence-auditor, lead-synthesiser]
|
||
purpose: "Performance budget negotiation and allocation tracking."
|
||
ucxl_feed: "ucxl://council-synth:trade-off-analyst@DistOS:integration/^^/docs/performance-budget.md"
|
||
|
||
- id: synth-coherence-audit
|
||
subscribers: [coherence-auditor, lead-synthesiser]
|
||
purpose: "Ongoing coherence audits: interface contract checks, consistency model alignment, dependency graph updates."
|
||
ucxl_feed: "ucxl://council-synth:coherence-auditor@DistOS:integration/^^/audits/*"
|
||
|
||
- id: synth-gacd-updates
|
||
subscribers: [lead-synthesiser, coherence-auditor]
|
||
purpose: "Coordination of GACD updates. Coherence Auditors propose section updates; Lead Synthesiser approves."
|
||
ucxl_feed: "ucxl://council-synth:lead-synthesiser@DistOS:integration/^^/docs/global-architectural-coherence.md"
|
||
|
||
- id: synth-meta-reporting
|
||
subscribers: [lead-synthesiser]
|
||
purpose: "Upward reporting to council-meta: blocked councils, open conflicts, synthesis health metrics."
|
||
ucxl_feed: "ucxl://council-synth:lead-synthesiser@DistOS:integration/^^/reports/meta-status-*"
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Success Criteria
|
||
|
||
1. **Zero open conflicts at Day 14:** Every conflict identified in the conflict registry has been either resolved (with a published resolution DR) or explicitly deferred with a documented risk assessment, accepted by `council-meta`.
|
||
|
||
2. **Consistency model certified:** The Consistency Model Alignment Report exists and is signed by at least 5 Coherence Auditors, confirming that `council-mem`, `council-net`, `council-fault`, and `council-api` consistency model choices are mutually compatible.
|
||
|
||
3. **Performance budget allocated and consistent:** Every subsystem has a latency budget derived from the top-level allocations in DP-S02. No subsystem's claimed performance targets exceed its allocated budget.
|
||
|
||
4. **Dependency graph is acyclic:** The dependency graph has been verified cycle-free at the end of each project phase. Any cycles detected were resolved within 24 hours.
|
||
|
||
5. **Interface contract registry complete:** Every inter-subsystem interface has an entry in the interface contract registry. Every contract is either verified by `council-verify` or explicitly flagged as pending with a resolution date.
|
||
|
||
6. **GACD maintained throughout:** The Global Architectural Coherence Document has been updated at least once per project day. It accurately reflects the state of all cross-cutting agreements at the time of project completion.
|
||
|
||
7. **ATAM utility tree complete:** The utility tree covers all six core quality attributes (performance, reliability, security, maintainability, developer experience, scalability) with at least three scenarios each, and identifies all major sensitivity and trade-off points.
|
||
|
||
8. **Response SLA met:** `council-synth` has acknowledged every conflict flagged by a Conflict Detector within 2 hours and opened a mini-council (or closed the non-conflict) within 4 hours.
|
||
|
||
9. **Evolutionary architecture policy ratified:** The policy exists, has been reviewed by `council-meta`, and is included in the final DistOS specification.
|
||
|
||
10. **Fitness functions defined and active:** At least five architectural fitness functions are defined in DP-S05 and are running against the UCXL artifact store by Day 6.
|
||
|
||
---
|
||
|
||
## 9. Timeline
|
||
|
||
### Phase 1: Research (Days 1–3)
|
||
|
||
`council-synth` is unique in that it must be operational from Day 1 — before any other council produces a DR. The first three days are therefore split between research (learning the methods) and operational setup (configuring the monitoring infrastructure).
|
||
|
||
- Lead Synthesiser and Coherence Auditors study ATAM methodology; conduct a dry run on a simple architectural question to validate process
|
||
- Trade-off Analysts study consistency model taxonomy (Viotti and Vukolić 2016; Bailis et al.); build reference table of consistency models available on the target hardware
|
||
- Conflict Detectors configure UCXL subscriptions to all council DR feeds; establish the triage queue; validate that feeds are operational
|
||
- Lead Synthesiser drafts the Conflict Resolution Process document (the rules of engagement for mini-councils)
|
||
- Performance budget top-level targets researched from hardware specifications; draft DP-S02 targets
|
||
- Construct initial dependency graph from the Project Constitution council structure
|
||
- Deliverable: `ucxl://council-synth:lead-synthesiser@DistOS:integration/^^/docs/conflict-resolution-process.md`
|
||
- Deliverable: `ucxl://council-synth:coherence-auditor@DistOS:integration/^^/graphs/dependency-graph.json` (initial)
|
||
|
||
### Phase 2: Architecture (Days 3–6)
|
||
|
||
- Resolve DP-S01 (consistency model), DP-S02 (performance budget), DP-S03 (escalation policy), DP-S04 (UCXL subscription architecture)
|
||
- First DRs arrive from subsystem councils; Conflict Detectors begin live monitoring
|
||
- Trade-off Analysts begin constructing the ATAM utility tree as architectural decisions arrive
|
||
- First mini-councils expected as subsystem councils begin making choices; arbitration process validated against real conflicts
|
||
- Coherence Auditors begin populating the interface contract registry as councils publish their interface requirements
|
||
- Performance budget draft distributed to all councils for comment
|
||
- Deliverable: `ucxl://council-synth:trade-off-analyst@DistOS:integration/^^/docs/atam-utility-tree.md` (draft)
|
||
- Deliverable: `ucxl://council-synth:trade-off-analyst@DistOS:integration/^^/docs/performance-budget.md` (draft)
|
||
|
||
### Phase 3: Formal Specification (Days 6–10)
|
||
|
||
- Peak conflict detection period: subsystem councils are writing formal specs and making concrete decisions; incompatibilities surface rapidly
|
||
- All Conflict Detectors at full monitoring capacity; daily conflict triage with Lead Synthesiser
|
||
- Trade-off Analysts provide ATAM analyses for every conflict requiring a mini-council
|
||
- Arbitrators run mini-councils; resolution DRs published within 8 hours of mini-council completion
|
||
- Coherence Auditors verify that interface contracts are being delivered to `council-verify` on schedule; flag any delays
|
||
- Consistency model alignment assessed as `council-mem`, `council-net`, and `council-fault` commit their specs
|
||
- Dependency graph updated daily; critical path reviewed to identify at-risk deliverables
|
||
- GACD updated with each major architectural decision
|
||
- Deliverable: First batch of conflict resolution DRs at `ucxl://council-synth:arbitrator@DistOS:integration/^^/decisions/*`
|
||
|
||
### Phase 4: Integration (Days 10–12)
|
||
|
||
- Conflict detection continues but should be declining in frequency as major architectural decisions have been made
|
||
- Focus shifts to Coherence Auditors: verify that integration-phase work respects all agreed constraints
|
||
- Consistency model alignment report drafted and circulated to affected councils for confirmation
|
||
- Performance budget final allocations agreed with all subsystem councils
|
||
- Evolutionary architecture policy drafted
|
||
- Dependency graph verified acyclic; any final critical-path risks escalated to `council-meta`
|
||
- `council-synth` issues formal directives to any council whose integration-phase work introduces new conflicts
|
||
- Deliverable: `ucxl://council-synth:coherence-auditor@DistOS:integration/^^/reports/consistency-model-alignment.md`
|
||
|
||
### Phase 5: Documentation (Days 12–14)
|
||
|
||
- Coherence Auditors conduct the final coherence audit; sign the synthesis final report
|
||
- All conflict registry entries confirmed resolved or deferred with accepted risk
|
||
- GACD finalised and submitted to `council-docs` for incorporation into the master specification
|
||
- Evolutionary architecture policy ratified by `council-meta` and published
|
||
- Lead Synthesiser writes the synthesis narrative for `council-arch`'s archaeological record
|
||
- Final architectural fitness functions verified active in the UCXL artifact store
|
||
- Deliverable: `ucxl://council-synth:lead-synthesiser@DistOS:integration/^^/reports/synthesis-final-report.md`
|
||
- Deliverable: `ucxl://council-synth:lead-synthesiser@DistOS:integration/^^/policies/evolutionary-architecture.md`
|