@snaptrude/plugin-core 0.9.17 → 0.9.18-edgesetbacks-20261021.1

package/src/api/program/adjacency.ts

@@ -1,164 +1,164 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-
-/**
- * Program adjacency — the proximity relationships between departments or
- * spaces.
- *
- * 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. Cell 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
- * {@linkcode PluginProgramAdjacencyApi.compute} first when you need fresh
- * data. Persisted matrices auto-hydrate on scene load, so warm reads are the
- * common case. The arrange/pack stages of the workflow live in
- * {@linkcode PluginProgramLayoutApi} (`program.layout`).
- *
- * Accessed via `snaptrude.program.adjacency`.
- */
-export abstract class PluginProgramAdjacencyApi {
-  constructor() {}
-
-  /**
-   * 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. Cell 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 — call
-   * {@linkcode PluginProgramAdjacencyApi.compute} first for fresh data
-   * (persisted matrices auto-hydrate on scene load, so warm reads are the
-   * common case). Space-level relationships are computed within a storey:
-   * cross-storey pairs always read `0`. At the `department` level the result
-   * also carries `departmentIds`, a parallel array joining each row to the
-   * department entity ids returned by `program.departments.list` (the row
-   * `ids` are department-mass component ids, not department entity ids).
-   *
-   * @param level - Read the `"department"` or `"space"` matrix.
-   * @param ids - Component ids to read a sub-matrix for, in this order
-   *   (defaults to every eligible element at the level).
-   * @returns A {@linkcode PluginProgramAdjacencyGetMatrixResult} with `ids`,
-   *   the square `matrix`, and (at department level) `departmentIds`.
-   * @throws If an id is unknown or does not match the requested level.
-   *
-   * @examplePrompt Get the space adjacency matrix
-   * @examplePrompt Which departments must be adjacent?
-   * @examplePrompt Show the adjacency relationships between departments
-   * @examplePrompt Read the adjacency matrix for these spaces
-   * @examplePrompt Which rooms are restricted from being next to each other?
-   *
-   * # Example
-   * ```ts
-   * const { ids, matrix } = await snaptrude.program.adjacency.getMatrix("department")
-   * ```
-   */
-  public abstract getMatrix(
-    level: PluginAdjacencyLevel,
-    ids?: string[],
-  ): PluginApiReturn<PluginProgramAdjacencyGetMatrixResult>
-
-  /**
-   * 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 A {@linkcode PluginProgramAdjacencyComputeResult} —
-   *   `{ success: true }` when the data is fresh or the run completed;
-   *   `{ success: false, error }` when the AI service could not be reached.
-   *
-   * @examplePrompt Refresh adjacency analysis
-   * @examplePrompt Compute the adjacency matrix for this project
-   * @examplePrompt Recalculate which departments should be adjacent
-   *
-   * # Example
-   * ```ts
-   * const { success } = await snaptrude.program.adjacency.compute()
-   * if (success) {
-   *   const data = await snaptrude.program.adjacency.getMatrix("space")
-   * }
-   * ```
-   */
-  public abstract compute(): PluginApiReturn<PluginProgramAdjacencyComputeResult>
-}
-
-/**
- * The level an adjacency matrix is read at.
- *
- * | Value | Description |
- * |---|---|
- * | `"department"` | One row/column per department mass |
- * | `"space"` | One row/column per space (within a storey) |
- */
-export const PluginAdjacencyLevel = z.enum(["department", "space"])
-export type PluginAdjacencyLevel = z.infer<typeof PluginAdjacencyLevel>
-
-/**
- * Arguments for {@linkcode PluginProgramAdjacencyApi.getMatrix}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `level` | {@linkcode 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) |
- */
-export const PluginProgramAdjacencyGetMatrixArgs = z.object({
-  level: PluginAdjacencyLevel,
-  ids: z.array(z.string()).optional(),
-})
-export type PluginProgramAdjacencyGetMatrixArgs = z.infer<
-  typeof PluginProgramAdjacencyGetMatrixArgs
->
-
-/**
- * Result of {@linkcode PluginProgramAdjacencyApi.getMatrix}.
- *
- * | 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 (joinable against `program.departments.list`), `null` when unassigned |
- * | `matrix` | `number[][]` | Square matrix aligned to `ids`; values in `{-1, 0, 1, 2}` |
- */
-export const PluginProgramAdjacencyGetMatrixResult = z.object({
-  ids: z.array(z.string()),
-  departmentIds: z.array(z.string().nullable()).optional(),
-  matrix: z.array(z.array(z.number())),
-})
-export type PluginProgramAdjacencyGetMatrixResult = z.infer<
-  typeof PluginProgramAdjacencyGetMatrixResult
->
-
-/**
- * Result of {@linkcode PluginProgramAdjacencyApi.compute}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `success` | `boolean` | `true` when the data is fresh or the run completed |
- * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
- */
-export const PluginProgramAdjacencyComputeResult = z.object({
-  success: z.boolean(),
-  error: z.string().optional(),
-})
-export type PluginProgramAdjacencyComputeResult = z.infer<
-  typeof PluginProgramAdjacencyComputeResult
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Program adjacency — the proximity relationships between departments or
+ * spaces.
+ *
+ * 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. Cell 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
+ * {@linkcode PluginProgramAdjacencyApi.compute} first when you need fresh
+ * data. Persisted matrices auto-hydrate on scene load, so warm reads are the
+ * common case. The arrange/pack stages of the workflow live in
+ * {@linkcode PluginProgramLayoutApi} (`program.layout`).
+ *
+ * Accessed via `snaptrude.program.adjacency`.
+ */
+export abstract class PluginProgramAdjacencyApi {
+  constructor() {}
+
+  /**
+   * 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. Cell 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 — call
+   * {@linkcode PluginProgramAdjacencyApi.compute} first for fresh data
+   * (persisted matrices auto-hydrate on scene load, so warm reads are the
+   * common case). Space-level relationships are computed within a storey:
+   * cross-storey pairs always read `0`. At the `department` level the result
+   * also carries `departmentIds`, a parallel array joining each row to the
+   * department entity ids returned by `program.departments.list` (the row
+   * `ids` are department-mass component ids, not department entity ids).
+   *
+   * @param level - Read the `"department"` or `"space"` matrix.
+   * @param ids - Component ids to read a sub-matrix for, in this order
+   *   (defaults to every eligible element at the level).
+   * @returns A {@linkcode PluginProgramAdjacencyGetMatrixResult} with `ids`,
+   *   the square `matrix`, and (at department level) `departmentIds`.
+   * @throws If an id is unknown or does not match the requested level.
+   *
+   * @examplePrompt Get the space adjacency matrix
+   * @examplePrompt Which departments must be adjacent?
+   * @examplePrompt Show the adjacency relationships between departments
+   * @examplePrompt Read the adjacency matrix for these spaces
+   * @examplePrompt Which rooms are restricted from being next to each other?
+   *
+   * # Example
+   * ```ts
+   * const { ids, matrix } = await snaptrude.program.adjacency.getMatrix("department")
+   * ```
+   */
+  public abstract getMatrix(
+    level: PluginAdjacencyLevel,
+    ids?: string[],
+  ): PluginApiReturn<PluginProgramAdjacencyGetMatrixResult>
+
+  /**
+   * 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 A {@linkcode PluginProgramAdjacencyComputeResult} —
+   *   `{ success: true }` when the data is fresh or the run completed;
+   *   `{ success: false, error }` when the AI service could not be reached.
+   *
+   * @examplePrompt Refresh adjacency analysis
+   * @examplePrompt Compute the adjacency matrix for this project
+   * @examplePrompt Recalculate which departments should be adjacent
+   *
+   * # Example
+   * ```ts
+   * const { success } = await snaptrude.program.adjacency.compute()
+   * if (success) {
+   *   const data = await snaptrude.program.adjacency.getMatrix("space")
+   * }
+   * ```
+   */
+  public abstract compute(): PluginApiReturn<PluginProgramAdjacencyComputeResult>
+}
+
+/**
+ * The level an adjacency matrix is read at.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"department"` | One row/column per department mass |
+ * | `"space"` | One row/column per space (within a storey) |
+ */
+export const PluginAdjacencyLevel = z.enum(["department", "space"])
+export type PluginAdjacencyLevel = z.infer<typeof PluginAdjacencyLevel>
+
+/**
+ * Arguments for {@linkcode PluginProgramAdjacencyApi.getMatrix}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `level` | {@linkcode 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) |
+ */
+export const PluginProgramAdjacencyGetMatrixArgs = z.object({
+  level: PluginAdjacencyLevel,
+  ids: z.array(z.string()).optional(),
+})
+export type PluginProgramAdjacencyGetMatrixArgs = z.infer<
+  typeof PluginProgramAdjacencyGetMatrixArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramAdjacencyApi.getMatrix}.
+ *
+ * | 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 (joinable against `program.departments.list`), `null` when unassigned |
+ * | `matrix` | `number[][]` | Square matrix aligned to `ids`; values in `{-1, 0, 1, 2}` |
+ */
+export const PluginProgramAdjacencyGetMatrixResult = z.object({
+  ids: z.array(z.string()),
+  departmentIds: z.array(z.string().nullable()).optional(),
+  matrix: z.array(z.array(z.number())),
+})
+export type PluginProgramAdjacencyGetMatrixResult = z.infer<
+  typeof PluginProgramAdjacencyGetMatrixResult
+>
+
+/**
+ * Result of {@linkcode PluginProgramAdjacencyApi.compute}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `boolean` | `true` when the data is fresh or the run completed |
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
+ */
+export const PluginProgramAdjacencyComputeResult = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+})
+export type PluginProgramAdjacencyComputeResult = z.infer<
+  typeof PluginProgramAdjacencyComputeResult
+>