architecture/group

Core group chapter for the architecture surface.

This folder owns the library's first composite graph primitive: a small collection of nodes that can be activated, propagated, wired, gated, and serialized as one architectural block.

Read this chapter in three passes:

1. start with the Group class overview to understand how the boundary wraps many node-level operations into one reusable building block,
2. continue to connect() and gate() when you need the structural vocabulary for wiring groups into larger graphs,
3. finish with disconnect(), clear(), and toJSON() when you want the lifecycle and persistence view for composite primitives.

Groups also carry the same two-level story as nodes: construction-time role describes the runtime semantics of their allocated nodes, while describe({ label, intent, metadata }) lets later tooling remember why this block exists without changing how activation or propagation works.

Example:

const sensorBlock = new Group(4, 'input');
const readoutBlock = new Group(2, 'output');

sensorBlock.describe({
  label: 'sensorBlock',
  metadata: { stage: 'encoder' },
});
readoutBlock.describe({
  label: 'readoutBlock',
  metadata: { stage: 'readout' },
});

sensorBlock.connect(
  readoutBlock,
  methods.groupConnection.ALL_TO_ALL,
);

architecture/group/group.ts

Group

Composite node block for architecture construction.

A group is the first place where the architecture surface stops talking about one primitive at a time and starts exposing small graph motifs. It owns a set of nodes plus the connection bookkeeping needed to treat that set as one wiring target, one wiring source, and one propagation unit.

This makes the boundary useful in three different modes:

• dense or structured connection building between graph regions,
• collective activation and propagation when a block should act as one unit,
• recurrent and gated substructures where node-level behavior is still needed but orchestration should stay above the single-neuron level.

The practical pattern is usually: allocate the group with the right runtime role when the whole block is clearly input- or output-oriented, then add a descriptor only when the boundary should stay visible in diagnostics or later graph assembly.

Example:

const sensorBlock = new Group(4, 'input');
const readoutBlock = new Group(2, 'output');

sensorBlock.describe({
  label: 'sensorBlock',
  metadata: { stage: 'encoder' },
});
readoutBlock.describe({
  label: 'readoutBlock',
  metadata: { stage: 'readout' },
});

sensorBlock.connect(
  readoutBlock,
  methods.groupConnection.ALL_TO_ALL,
);

default

activate

activate(
  value: number[] | undefined,
): number[]

Activates all nodes in the group.

Parameters:

• value - Optional array of input values. Its length must match the number of nodes in the group.

Returns: Activation value of each node in the group, in order.

clear

clear(): void

Resets the state of all nodes in the group.

Returns: Nothing.

connect

connect(
  target: default | default | default,
  method: unknown,
  weight: number | undefined,
): default[]

Establishes connections from all nodes in this group to a target group, layer, or node.

Parameters:

• target - Destination entity to connect to.
• method - Connection pattern to use.
• weight - Optional fixed weight for all created connections.

Returns: All connection objects created during this wiring step.

connections

Stores connection information related to this group. in: Connections coming into nodes in this group from outside. out: Connections going out from nodes in this group to outside. self: Connections between nodes within this same group.

describe

describe(
  descriptor: PrimitiveDescriptor,
): void

Attaches optional descriptor metadata to the group boundary.

Use this when a group represents a named stage, gate bundle, or other meaningful architecture unit that later diagnostics should recognize without inferring from node order alone.

Parameters:

• descriptor - Optional label, intent, and scalar metadata to merge.

Returns: Nothing.

Example:

const forgetGate = new Group(8);

forgetGate.describe({
  label: 'forgetGate',
  intent: 'gate',
  metadata: { family: 'lstm' },
});

disconnect

disconnect(
  target: default | default,
  twosided: boolean,
): void

Removes connections between nodes in this group and a target group or node.

Parameters:

• target - Group or node to disconnect from.
• twosided - Whether to also remove reciprocal connections.

Returns: Nothing.

gate

gate(
  connections: default | default[],
  method: unknown,
): void

Configures nodes within this group to act as gates for the specified connection set.

Parameters:

• connections - Single connection or list of connections to gate.
• method - Gating mechanism to use.

Returns: Nothing.

intent

Optional semantic intent for architecture tooling and diagnostics.

label

Optional human-readable descriptor label for architecture tooling.

metadata

Optional scalar metadata retained on the primitive boundary.

nodes

An array holding all the nodes within this group.

propagate

propagate(
  rate: number,
  momentum: number,
  target: number[] | undefined,
): void

Propagates the error backward through all nodes in the group.

Parameters:

• rate - Learning rate to apply during weight updates.
• momentum - Momentum factor to apply during weight updates.
• target - Optional target values for error calculation. Its length must match the number of nodes.

Returns: Nothing.

set

set(
  values: { bias?: number | undefined; squash?: ((x: number, derivate?: boolean | undefined) => number) | undefined; type?: string | undefined; },
): void

Sets specific properties for all nodes within the group.

Parameters:

• values - Property values to apply to every node.

Returns: Nothing.

toJSON

toJSON(): { size: number; nodeIndices: (number | undefined)[]; connections: { in: number; out: number; self: number; }; }

Serializes the group into a JSON-compatible format, avoiding circular references.

Returns: JSON-friendly representation with node indices and connection counts.

architecture/group/group.errors.ts

Raised when caller-provided group values do not match the number of nodes.

GroupGatingMethodRequiredError

Raised when gating is requested without specifying a gating method.

GroupOneToOneSizeMismatchError

Raised when ONE_TO_ONE group connections are requested for groups of different sizes.

GroupSizeMismatchError

Raised when caller-provided group values do not match the number of nodes.

architecture/group/group.utils.ts

Structural helper utilities for the Group connect, gate, and disconnect operations.

These helpers are extracted from the Group class methods to keep each public method below the complexity threshold. All functions are pure structural utilities — they do not hold state and have no side-effects beyond the explicit mutation of the arguments they receive.

collectUniqueSourceNodes

collectUniqueSourceNodes(
  connections: default[],
): default[]

Collect unique source nodes referenced by a set of connections.

Preserves first-seen order so gating index assignment is deterministic.

Parameters:

• connections - The connections to extract unique source nodes from.

Returns: The list of unique source nodes in first-seen order.

connectAllToAll

connectAllToAll(
  source: default,
  target: default,
  method: unknown,
  weight: number | undefined,
): default[]

Connect source group to target group using ALL_TO_ALL or ALL_TO_ELSE semantics.

Skips self-pairs when ALL_TO_ELSE is requested. Registers every created connection on both groups' bookkeeping lists.

Parameters:

• source - The source group to connect from.
• target - The target group to connect to.
• method - The connection method (ALL_TO_ALL or ALL_TO_ELSE).
• weight - Optional fixed weight to apply to each new connection.

Returns: The list of created connections.

connectGroupToGroup

connectGroupToGroup(
  source: default,
  target: default,
  method: unknown,
  weight: number | undefined,
): default[]

Connect source group to target group, dispatching to the correct connection method.

Resolves a default method when none is provided and delegates to ALL_TO_ALL, ALL_TO_ELSE, or ONE_TO_ONE helpers.

Parameters:

• source - The source group to connect from.
• target - The target group to connect to.
• method - Optional connection method override.
• weight - Optional fixed weight to apply to each new connection.

Returns: The list of created connections.

connectGroupToLayer

connectGroupToLayer(
  source: default,
  target: default,
  method: unknown,
  weight: number | undefined,
): default[]

Connect source group to target layer, delegating to the layer's input method.

Parameters:

• source - The source group to connect from.
• target - The target layer to connect to.
• method - Optional connection method override.
• weight - Optional fixed weight to apply to each new connection.

Returns: The list of created connections.

connectGroupToNode

connectGroupToNode(
  source: default,
  target: default,
  weight: number | undefined,
): default[]

Connect every node in source group to a single target node.

Registers each created connection on the source group's outbound list.

Parameters:

• source - The source group whose nodes will each connect to the target.
• target - The single target node to connect every source node to.
• weight - Optional fixed weight to apply to each new connection.

Returns: The list of created connections.

connectOneToOne

connectOneToOne(
  source: default,
  target: default,
  weight: number | undefined,
): default[]

Connect source group to target group using ONE_TO_ONE semantics.

Throws when the groups differ in size. Registers self-connections on the self shelf when source and target are the same group object.

Parameters:

• source - The source group to connect from.
• target - The target group to connect to.
• weight - Optional fixed weight to apply to each new connection.

Returns: The list of created connections.

disconnectGroupFromGroup

disconnectGroupFromGroup(
  source: default,
  target: default,
  twosided: boolean,
): void

Disconnect every source node in the group from every target node in another group.

Also removes the disconnected connections from both groups' bookkeeping lists. When twosided is true, the reverse connections are removed as well.

Parameters:

• source - The source group whose nodes are disconnected.
• target - The target group whose nodes are disconnected from.
• twosided - Whether to remove reciprocal connections as well.

disconnectGroupFromNode

disconnectGroupFromNode(
  source: default,
  target: default,
  twosided: boolean,
): void

Disconnect every node in the group from a single target node.

Removes the disconnected connections from the source group's outbound list. When twosided is true, reverse connections are removed from the inbound list.

Parameters:

• source - The source group whose nodes are disconnected.
• target - The single target node to disconnect from.
• twosided - Whether to remove reciprocal connections as well.

gateByInput

gateByInput(
  group: default,
  gatedConnections: default[],
): void

Apply INPUT gating: assign each connection to the group node at connection-index modulo group size.

Parameters:

• group - The group whose nodes act as gaters.
• gatedConnections - The connections to gate.

gateByOutput

gateByOutput(
  group: default,
  gatedConnections: default[],
  sourceNodes: default[],
): void

Apply OUTPUT gating: for each source node, gate its matching outbound connections.

Parameters:

• group - The group whose nodes act as gaters.
• gatedConnections - The connections to gate.
• sourceNodes - The unique source nodes whose outbound connections are gated.

gateBySelf

gateBySelf(
  group: default,
  gatedConnections: default[],
  sourceNodes: default[],
): void

Apply SELF gating: for each source node, gate its self-connection when present in the set.

Parameters:

• group - The group whose nodes act as gaters.
• gatedConnections - The connections to gate.
• sourceNodes - The unique source nodes whose self-connections are gated.

removeInboundConnection

removeInboundConnection(
  connectionList: default[],
  from: default,
  to: default,
): void

Remove the first matching inbound connection from a connection list.

Mirrors removeOutboundConnection for the receiving side of an edge.

Parameters:

• connectionList - The inbound connection list to search and mutate.
• from - The source node of the connection to remove.
• to - The target node of the connection to remove.

removeOutboundConnection

removeOutboundConnection(
  connectionList: default[],
  from: default,
  to: default,
): void

Remove the first matching outbound connection from a connection list.

Walks the list in reverse to avoid index-shift errors during splice. Stops after the first removal because each source/target pair appears at most once.

Parameters:

• connectionList - The outbound connection list to search and mutate.
• from - The source node of the connection to remove.
• to - The target node of the connection to remove.

resolveDefaultGroupConnectionMethod

resolveDefaultGroupConnectionMethod(
  source: default,
  target: default,
): unknown

Resolve the default group-connection method when none is provided by the caller.

Returns ALL_TO_ALL for distinct source/target groups and ONE_TO_ONE when a group is wired to itself, emitting a console warning for each case when warnings are enabled.

Parameters:

• source - The source group whose connection method is being resolved.
• target - The target group to connect to.

Returns: The resolved group-connection method (ALL_TO_ALL or ONE_TO_ONE).