# SCX Authoritative Platform and Governance Guide

## What changed

The planning suite now separates proposals and derived evidence from one controlled `authoritative-project` artifact. Layout files, demand imports, optimisation studies, calculation sets and AI reviews do not become design authority automatically. A named canonical model must be promoted through the Governance Console using optimistic version control.

Open `http://127.0.0.1:8840/scx_governance_console.html`.

## First administrator and sign-in

On first use, enter a username, display name and password of at least 12 characters, then choose **Create first administrator**. Before this bootstrap the existing local tools operate in compatibility mode. After bootstrap, the server enforces role permissions and all users must sign in. Sessions use an eight-hour, HTTP-only, same-site cookie. For access beyond the local workstation, place the application behind TLS and an organisation-approved reverse proxy or identity provider.

## Roles

- **Viewer** — read controlled information.
- **Planner** — edit layouts and demand, run optimisation, and exchange coordination data.
- **Engineer** — perform engineering edits, calculations, AI review and submit engineering review.
- **Checker** — perform independent checks, without authoring authority.
- **Approver** — approve controlled release gates.
- **Administrator** — manage users and has all application permissions.

The API checks permissions; hiding a button is not the security boundary.

## Authoritative project workflow

1. Develop a proposal in the planning and canonical tools.
2. Load the existing authoritative version in the Governance Console.
3. Load the current planner model as the proposed change.
4. Run canonical, calculation, constraint, spatial and optimisation checks.
5. Commit with a meaningful change note. The commit is rejected if another user has changed the authoritative version since it was loaded.
6. Record engineering review, independent check and approval decisions against the exact model hash.

The model author cannot independently check or approve the same authoritative revision.

## Spatial engineering engine

The engine converts canonical assets and stations into SI-metre 3D axis-aligned bounding boxes, preserves the project coordinate reference, builds topology from trace links, generates conservative movement swept volumes, detects solid intersections, and checks configurable 3D clearance envelopes. Every report includes assumptions, tolerance, model hash and a spatial evidence hash.

Default asset widths and heights are explicit assumptions, not surveyed geometry. Replace them with verified manufacturer and survey envelopes before release. Axis-aligned screening is conservative but does not replace detailed solid modelling or dynamic collision analysis.

## Optimisation methods

For studies of up to 12 moves, the engine uses exact branch-and-bound capacitated minimax assignment and reports its explored search nodes. Larger studies use deterministic multi-start, large-neighbourhood list scheduling across throughput, balanced, cost and resilience objective profiles. Hard physical constraints gate every recommendation. The output records the solver, assumptions, allocations, failures, objective values and study hash.

An exact assignment result proves only the implemented assignment objective. Timing, operational variability and structural feasibility remain separate verification obligations.

## Industrial interoperability

- SCX exchange JSON for loss-minimising round trips.
- Geometry CSV for schedules and controlled mapping.
- Layered DXF for 2D coordination.
- IFC4 proxy coordination objects with embedded SCX round-trip metadata.
- buildingSMART IDS requirements for IFC information checking.
- BCF 2.1 issue packages generated from spatial collisions and clearance findings.
- OPC UA NodeSet2 asset nodes for controls/integration preparation.

Confirm units, origin, axes, elevations, object mapping and revisions at every interface. IFC proxy and OPC UA outputs are coordination starters, not a complete manufacturer-specific product model or controls implementation.

## Controlled AI

AI review is advisory. The server adds input and review hashes and marks the result `advisory-unaccepted`. AI cannot write the authoritative model, override deterministic constraints, approve a gate or certify a design. An engineer must explicitly accept or reject a review; that decision is stored as a separate repository artifact.

Do not include secrets, personal data or export-controlled content unless the configured AI service and organisational policy permit it.

## Professional limitations

Role access in this local standard-library server is suitable for controlled team use on a protected network. For enterprise deployment, integrate corporate SSO/MFA, central secrets, TLS, backups, retention rules, security monitoring and periodic access review. Engineering outputs still require competent-person review and compliance with the project’s applicable standards and statutory regime.