Adjacency

The proximity relationships between departments or spaces. Accessed via snaptrude.program.adjacency.

Adjacency is stage one of the product's space-planning workflow (compute → arrange → pack): the AI service scores which program elements need to be near each other, and the geometry contributes physical contact. Every matrix cell holds one of four values:

Value	Meaning
2	Direct — adjacency required
1	Indirect — nearby preferred, or physical contact
-1	Restricted — must NOT be adjacent
0	No relationship — or adjacency was never computed

Zeros are ambiguous by design (the engine cannot distinguish "no relationship" from "never computed"): call compute() first when you need fresh data. Persisted matrices auto-hydrate on project load, so warm reads are the common case. Space-level relationships are computed within a storey — cross-storey pairs always read 0.

The per-space view of the same data is available as the adjacency field of snaptrude.design.query.getProperties (formerly the "adjacency" property of the deprecated entity.space.get).

At a glance

Method	What it does	Mutates?
getMatrix(level, ids?)	Read the adjacency matrix at a level	—
compute()	Run (or refresh) the AI adjacency precompute	✓

Types

PluginAdjacencyLevel

The level an adjacency matrix is read at: "department" | "space".

Value	Description
"department"	One row/column per department mass
"space"	One row/column per space (within a storey)

PluginProgramAdjacencyGetMatrixResult

An adjacency matrix aligned to component ids.

Property	Type	Description
ids	string[]	Component ids, in matrix row/column order
departmentIds	(string | null)[] | undefined	Department level only: parallel to ids, the department entity id each row belongs to, null when unassigned
matrix	number[][]	Square matrix aligned to ids; values in {-1, 0, 1, 2}

At the department level the row ids are department-mass component ids, not the department entity ids that snaptrude.program.departments.list returns — join the two via the parallel departmentIds array.

PluginProgramAdjacencyComputeResult

Property	Type	Description
success	boolean	true when the data is fresh or the run completed
error	string | undefined	Failure reason when success is false

Functions

getMatrix(level, ids?)

Read the adjacency matrix at the department or space level. Returns a square matrix whose rows/columns are aligned to ids (component ids). Pass ids to read a sub-matrix in that order; omit it to get every eligible element at that level.

• Parameters:
  • level: PluginAdjacencyLevel — read the "department" or "space" matrix
  • ids: string[] | undefined — component ids to read a sub-matrix for, in this order (defaults to every eligible element at the level)
• Returns: PluginProgramAdjacencyGetMatrixResult — ids, the square matrix, and (at department level) departmentIds.
• Throws: If an id is unknown or does not match the requested level (e.g. a space id with level: "department").

const { ids, departmentIds, matrix } = await snaptrude.program.adjacency.getMatrix("department");
for (let i = 0; i < ids.length; i++) console.log(ids[i], departmentIds?.[i], matrix[i]);

---

compute()

Compute (or refresh) the adjacency data for the project. Runs the AI adjacency precompute and persists the result; a no-op when the stored data is already fresh. A real run takes ~2s at minimum (engine pacing) plus the AI service round-trip.

This is a write — it mutates and persists project analysis data — so it is blocked when plugin writes are disabled.

• Returns: PluginProgramAdjacencyComputeResult — { success: true } when the data is fresh or the run completed; { success: false, error } when the AI service could not be reached.
• Throws: If plugin writes are disabled.

const { success, error } = await snaptrude.program.adjacency.compute();
if (success) {
  const { ids, matrix } = await snaptrude.program.adjacency.getMatrix("space");
} else {
  console.warn("Adjacency compute failed:", error);
}

Errors

Failed calls reject with a typed PluginError — see Error Handling. Conditions specific to this namespace:

Code	Thrown by	When	details
HANDLE_INVALID	getMatrix	An explicit id is unknown or does not resolve to a mass	—
PRECONDITION_FAILED	getMatrix	An id resolves to a mass at the wrong level (e.g. a space id with level: "department")	handles — the offending id; level — the level requested

compute reports AI-service / precompute failures in-band as { success: false, error } rather than rejecting — it only rejects when plugin write APIs are disabled (METHOD_NOT_PERMITTED).