nested

package
v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 5, 2026 License: GPL-3.0 Imports: 27 Imported by: 0

Documentation

Overview

Package nested binds and plans the closed nested-mutation vocabulary before any transaction or provider boundary. It produces only canonical mutation IR and explicit bounded database-expansion requirements.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExecuteRelationSQL 

func ExecuteRelationSQL(ctx context.Context, queryer sqlx.QueryerContext, registry *schema.Registry, provider policyir.Provider, statement RelationSQLStatement) ([]mutationdecode.Row, error)

ExecuteRelationSQL runs one already-rendered relation statement on the caller-owned transaction/queryer and decodes only through the active schema. Expansion cardinality is refused (not truncated) when the renderer's sentinel row is observed. Membership writes must affect exactly one row.

func RelationSetDifference 

func RelationSetDifference(registry *schema.Registry, current, desired []mutationdecode.Row) (connect, disconnect []mutationdecode.Row, err error)

RelationSetDifference computes exact membership effects over primary identities. Inputs may arrive in any order; outputs are canonical and duplicate identities fail closed rather than silently collapsing rows.

Types

type AppliedNode 

type AppliedNode struct {
	// contains filtered or unexported fields
}

func (AppliedNode) Node 

func (applied AppliedNode) Node() mutationir.Node

func (AppliedNode) Result 

func (applied AppliedNode) Result() ApplyResult

func (AppliedNode) Work 

func (applied AppliedNode) Work() RuntimeWork

type ApplyRequest 

type ApplyRequest struct {
	// contains filtered or unexported fields
}

func (ApplyRequest) Dependencies 

func (request ApplyRequest) Dependencies() []AppliedNode

func (ApplyRequest) Node 

func (request ApplyRequest) Node() mutationir.Node

func (ApplyRequest) Parent 

func (request ApplyRequest) Parent() (AppliedNode, bool)

func (ApplyRequest) RelationAnchor 

func (request ApplyRequest) RelationAnchor() (AppliedNode, bool)

func (ApplyRequest) Work 

func (request ApplyRequest) Work() RuntimeWork

type ApplyResult 

type ApplyResult struct {
	// contains filtered or unexported fields
}

func NewApplyResult 

func NewApplyResult(before, after *mutationdecode.Row) ApplyResult

func WithRuntimeHookResult 

func WithRuntimeHookResult(result ApplyResult, hook golem.RuntimeMutationHookResult) ApplyResult

func (ApplyResult) After 

func (result ApplyResult) After() (mutationdecode.Row, bool)

func (ApplyResult) Before 

func (result ApplyResult) Before() (mutationdecode.Row, bool)

func (ApplyResult) RuntimeHookResult 

func (result ApplyResult) RuntimeHookResult() (golem.RuntimeMutationHookResult, bool)

type BeforeParentTransaction 

type BeforeParentTransaction interface {
	BeginBeforeParent(context.Context, mutationir.Node) error
	CompleteBeforeParent(context.Context, mutationir.Node) error
}

BeforeParentTransaction preserves declared graph observability when a source dependency must execute physically before its parent row. The transaction may checkpoint and restore graph-ordered side effects such as outbox ordinals around the physical dependency segment.

type BoundaryFunc 

type BoundaryFunc func(context.Context) (ExecutionTransaction, error)

BoundaryFunc adapts a runtime-owned transaction opener without coupling the provider-neutral nested engine to sqlx or to one provider's begin primitive.

func (BoundaryFunc) BeginNested 

func (open BoundaryFunc) BeginNested(ctx context.Context) (ExecutionTransaction, error)

type Classifier 

type Classifier interface {
	Fields(classify.Request) (classify.Plan, error)
}

type DynamicTransformTransaction 

type DynamicTransformTransaction interface {
	TransformNested(context.Context, TransformRequest) (SubtreeReplacement, bool, error)
}

DynamicTransformTransaction is the exact selected-child Before-hook seam.

Direct scalar branches are offered at TransformPreExpand only after their COC/upsert container selected them and before selector/filter expansion SQL. Membership owner updates are offered at TransformPostExpand after an exact owner RuntimeWork is locked but before Apply SQL. A replacement is a local, deterministic graph; Entry identifies its selected root while any dummy anchor node is not executed. Local ordinals need not match the discarded global subtree. The engine supplies the already-applied external parent and relation anchor to Entry. Membership replacement must retain Work's exact identity; the runtime validator rejects a changed target before returning it.

type Error 

type Error struct {
	Code   ErrorCode
	Model  golem.ModelID
	Field  golem.FieldID
	Detail string
	Cause  error
}

func (*Error) Error 

func (failure *Error) Error() string

func (*Error) Unwrap 

func (failure *Error) Unwrap() error

type ErrorCode 

type ErrorCode string
const (
	CodeInput          ErrorCode = "P4_NESTED_INPUT"
	CodeRelation       ErrorCode = "P4_NESTED_RELATION"
	CodeShape          ErrorCode = "P4_NESTED_SHAPE"
	CodeExposure       ErrorCode = "P4_NESTED_EXPOSURE"
	CodeDepth          ErrorCode = "P4_NESTED_DEPTH"
	CodeBinding        ErrorCode = "P4_NESTED_BINDING"
	CodePolicy         ErrorCode = "P4_NESTED_POLICY"
	CodeClassification ErrorCode = "P4_NESTED_CLASSIFICATION"
	CodeIR             ErrorCode = "P4_NESTED_IR"
)

type ExecutionBoundary 

type ExecutionBoundary interface {
	BeginNested(context.Context) (ExecutionTransaction, error)
}

ExecutionBoundary is the provider/runtime seam for the nested engine. One Begin call covers the complete graph; the engine never opens a transaction per node or per dynamically expanded row.

type ExecutionReceipt 

type ExecutionReceipt struct {
	// contains filtered or unexported fields
}

func Execute 

func Execute(ctx context.Context, graph mutationir.Graph, maxTouchedRows uint32, boundary ExecutionBoundary) (receipt ExecutionReceipt, err error)

Execute performs deterministic depth-first expansion and writes, then reverse-order verification, on exactly one transaction. Any expansion, write, verification, limit, context, or commit error attempts rollback.

func (ExecutionReceipt) Applied 

func (receipt ExecutionReceipt) Applied() []AppliedNode

func (ExecutionReceipt) TouchedRows 

func (receipt ExecutionReceipt) TouchedRows() uint32

type ExecutionTransaction 

type ExecutionTransaction interface {
	ExpandNested(context.Context, ExpansionRequest) (RuntimeExpansion, error)
	ApplyNested(context.Context, ApplyRequest) (ApplyResult, error)
	VerifyNested(context.Context, AppliedNode) error
	CommitNested(context.Context) error
	RollbackNested(context.Context) error
}

ExecutionTransaction is implemented by the runtime adapter. ExpandNested resolves target sets and truthful branches using provider SQL. ApplyNested delegates row writes to the scalar, batch, and upsert kernels. VerifyNested is called in reverse depth-first order after every write has succeeded.

type ExpansionRequest 

type ExpansionRequest struct {
	// contains filtered or unexported fields
}

func (ExpansionRequest) Node 

func (request ExpansionRequest) Node() mutationir.Node

func (ExpansionRequest) Parent 

func (request ExpansionRequest) Parent() (AppliedNode, bool)

func (ExpansionRequest) RelationAnchor 

func (request ExpansionRequest) RelationAnchor() (AppliedNode, bool)

type FinalGraphTransaction 

type FinalGraphTransaction interface {
	FinalizeNested(context.Context, []AppliedNode) error
}

type HookSource 

type HookSource struct {
	// contains filtered or unexported fields
}

HookSource retains the frozen generated branch that produced one nested write node. It is runtime provenance, not mutation-plan semantics.

func (HookSource) Action 

func (source HookSource) Action() golem.MutationRelationAction

func (HookSource) Branch 

func (source HookSource) Branch() (golem.FrozenNestedMutationBranch, bool)

func (HookSource) FieldID 

func (source HookSource) FieldID() golem.FieldID

func (HookSource) ParentModelID 

func (source HookSource) ParentModelID() golem.ModelID

func (HookSource) RelationID 

func (source HookSource) RelationID() golem.RelationID

func (HookSource) TargetModelID 

func (source HookSource) TargetModelID() golem.ModelID

type MembershipEffect 

type MembershipEffect uint8
const (
	MembershipConnect MembershipEffect = iota + 1
	MembershipDisconnect
)

type MembershipSQLRequest 

type MembershipSQLRequest struct {
	Node          mutationir.Node
	Anchor        mutationdecode.Row
	Related       mutationdecode.Row
	Effect        MembershipEffect
	Registry      *schema.Registry
	Provider      policyir.Provider
	MaxParameters uint32
}

type NotFoundError 

type NotFoundError struct {
	Model policyir.ModelID
	Field policyir.FieldID
}

NotFoundError is the execution-time result of resolving one exact nested selector/current-to-one position to no row. It is deliberately typed so the public runtime can give missing and caller-invisible targets identical NOT_FOUND semantics without parsing provider/cardinality error strings.

func (*NotFoundError) Error 

func (failure *NotFoundError) Error() string

type PositionAudit 

type PositionAudit struct {
	// contains filtered or unexported fields
}

PositionAudit is proof that one selector/filter position was classified during the pre-graph phase. Zero Fields is valid only for explicit All.

func (PositionAudit) FieldID 

func (audit PositionAudit) FieldID() policyir.FieldID

func (PositionAudit) Fields 

func (audit PositionAudit) Fields() []policyir.FieldID

func (PositionAudit) ModelID 

func (audit PositionAudit) ModelID() policyir.ModelID

func (PositionAudit) Operation 

func (audit PositionAudit) Operation() mutationir.Operation

func (PositionAudit) ParentModelID 

func (audit PositionAudit) ParentModelID() policyir.ModelID

func (PositionAudit) UseKind 

func (audit PositionAudit) UseKind() classify.UseKind

type RelationExpansionSQLRequest 

type RelationExpansionSQLRequest struct {
	Node          mutationir.Node
	Anchor        mutationdecode.Row
	Registry      *schema.Registry
	Provider      policyir.Provider
	Capabilities  policysql.CapabilityProof
	MaxRows       uint32
	MaxParameters uint32
}

type RelationSQLColumn 

type RelationSQLColumn struct {
	// contains filtered or unexported fields
}

func (RelationSQLColumn) Alias 

func (column RelationSQLColumn) Alias() string

func (RelationSQLColumn) FieldID 

func (column RelationSQLColumn) FieldID() policyir.FieldID

type RelationSQLProgram 

type RelationSQLProgram struct {
	// contains filtered or unexported fields
}

func RenderRelationExpansion 

func RenderRelationExpansion(request RelationExpansionSQLRequest) (RelationSQLProgram, error)

RenderRelationExpansion renders only descriptor-owned identifiers. Runtime anchor values, selector values, guards, and predicates are fully bound. Correlation pairs are emitted in normalized RelationIR order.

func (RelationSQLProgram) Statements 

func (program RelationSQLProgram) Statements() []RelationSQLStatement

type RelationSQLRole 

type RelationSQLRole uint8
const (
	ExpandRelatedRows RelationSQLRole = iota + 1
	ExpandCurrentMembership
	ExpandDesiredTarget
	ApplyMembershipConnect
	ApplyMembershipDisconnect
)

type RelationSQLStatement 

type RelationSQLStatement struct {
	// contains filtered or unexported fields
}

func RenderMembershipWrite 

func RenderMembershipWrite(request MembershipSQLRequest) (RelationSQLStatement, error)

RenderMembershipWrite updates the actual FK-owning row. Source endpoints write parent correlation fields from the selected/created target row; inverse endpoints write target correlation fields from the anchor row.

func (RelationSQLStatement) Args 

func (statement RelationSQLStatement) Args() []any

func (RelationSQLStatement) Columns 

func (statement RelationSQLStatement) Columns() []RelationSQLColumn

func (RelationSQLStatement) MaxRows 

func (statement RelationSQLStatement) MaxRows() uint32

func (RelationSQLStatement) ModelID 

func (statement RelationSQLStatement) ModelID() policyir.ModelID

func (RelationSQLStatement) Role 

func (statement RelationSQLStatement) Role() RelationSQLRole

func (RelationSQLStatement) SQL 

func (statement RelationSQLStatement) SQL() string

type Request 

type Request struct {
	Root      mutationir.NodeInput
	Mutations []golem.FrozenNestedMutation
	Stance    mutationir.Stance
	Registry  *schema.Registry
	Policies  mutationplan.PolicySet
	// HookInventory returns generated hook metadata for the exact owning model.
	// A nil callback is the explicit empty inventory used by schemas with no
	// hooks; runtime supplies this callback from generated bindings.
	HookInventory func(policyir.ModelID) mutationplan.HookInventory
	// SourceOffset reserves runtime provenance identities already retained by
	// an enclosing dynamic compilation. It does not affect semantic graph
	// ordinals or canonical plan encoding.
	SourceOffset uint32
	Classifier   Classifier
	MaxDepth     uint16
	MaxRows      uint32
	// RuntimeValues materializes application-owned defaults/updated fields
	// after stable runtime source slots have been assigned and before semantic
	// graph ordinals are frozen. Nil means no runtime-owned materialization.
	RuntimeValues func(mutationir.NodeInput) (mutationir.NodeInput, error)
}

type Result 

type Result struct {
	// contains filtered or unexported fields
}

func Build 

func Build(request Request) (Result, error)

func (Result) Graph 

func (result Result) Graph() mutationir.Graph

func (Result) HookSource 

func (result Result) HookSource(node mutationir.Node) (HookSource, bool)

func (Result) PositionAudits 

func (result Result) PositionAudits() []PositionAudit

func (Result) SourceUpperBound 

func (result Result) SourceUpperBound() uint32

type RuntimeExpansion 

type RuntimeExpansion struct {
	// contains filtered or unexported fields
}

func ExpandRelationSQL 

func ExpandRelationSQL(ctx context.Context, request SQLExpansionRequest) (RuntimeExpansion, error)

ExpandRelationSQL is the production database-expansion half of the nested TransactionAdapter. It covers every relation-position kind, truthful branch selection, source/inverse ownership, and exact set-difference effects. Root scalar expansion remains runtime-owned because its locked image is produced by the scalar mutation program itself.

func NewRuntimeExpansion 

func NewRuntimeExpansion(works []RuntimeWork, branch mutationir.Branch) (RuntimeExpansion, error)

func (RuntimeExpansion) Branch 

func (expansion RuntimeExpansion) Branch() mutationir.Branch

func (RuntimeExpansion) Works 

func (expansion RuntimeExpansion) Works() []RuntimeWork

type RuntimeWork 

type RuntimeWork struct {
	// contains filtered or unexported fields
}

func ExistingRelationWorks 

func ExistingRelationWorks(registry *schema.Registry, rows []mutationdecode.Row, effect MembershipEffect) ([]RuntimeWork, error)

ExistingRelationWorks converts locked target rows for an inverse endpoint into immutable execution work. Each row owns its own FK membership.

func ExistingRowWork 

func ExistingRowWork(registry *schema.Registry, row mutationdecode.Row) (RuntimeWork, error)

ExistingRowWork derives both execution identity and canonical ordering from the active model's declared primary key. Composite component order is never inferred from field IDs or physical column order.

func NewBatchWork 

func NewBatchWork(model policyir.ModelID, rows []mutationdecode.Row, orderKey []byte) (RuntimeWork, error)

NewBatchWork represents one exact, already-locked dynamic batch. Apply is invoked once so the batch kernel can authorize all chunks before any write; touched-row accounting still uses the exact row cardinality.

func NewCreateWork 

func NewCreateWork(model policyir.ModelID, orderKey []byte) (RuntimeWork, error)

func NewExistingWork 

func NewExistingWork(model policyir.ModelID, identity mutationdecode.Identity, orderKey []byte) (RuntimeWork, error)

func NewResolvedRelationWork 

func NewResolvedRelationWork(workModel policyir.ModelID, identity mutationdecode.Identity, orderKey []byte, row mutationdecode.Row, effect MembershipEffect) (RuntimeWork, error)

NewResolvedRelationWork retains the locked related row required by a later membership write. workModel is the FK owner and may differ from row.ModelID for a source endpoint. effect is non-zero only for set-difference work.

func OwnerRelationWork 

func OwnerRelationWork(registry *schema.Registry, owner, related mutationdecode.Row, effect MembershipEffect) (RuntimeWork, error)

OwnerRelationWork represents a source endpoint: the work identity belongs to the FK-owning anchor while the retained row is the resolved target.

func (RuntimeWork) BatchRows 

func (work RuntimeWork) BatchRows() ([]mutationdecode.Row, bool)

func (RuntimeWork) Identity 

func (work RuntimeWork) Identity() (mutationdecode.Identity, bool)

func (RuntimeWork) MembershipEffect 

func (work RuntimeWork) MembershipEffect() MembershipEffect

func (RuntimeWork) ModelID 

func (work RuntimeWork) ModelID() policyir.ModelID

func (RuntimeWork) OrderKey 

func (work RuntimeWork) OrderKey() []byte

func (RuntimeWork) ResolvedRelationRow 

func (work RuntimeWork) ResolvedRelationRow() (mutationdecode.Row, bool)

func (RuntimeWork) TouchedRows 

func (work RuntimeWork) TouchedRows() uint32

type SQLExpansionRequest 

type SQLExpansionRequest struct {
	Expansion     ExpansionRequest
	Queryer       sqlx.QueryerContext
	Registry      *schema.Registry
	Provider      policyir.Provider
	Capabilities  policysql.CapabilityProof
	MaxRows       uint32
	MaxParameters uint32
}

type SubtreeReplacement 

type SubtreeReplacement struct {
	// contains filtered or unexported fields
}

func NewSubtreeReplacement 

func NewSubtreeReplacement(graph mutationir.Graph, entry uint32) (SubtreeReplacement, error)

func (SubtreeReplacement) EntryOrdinal 

func (replacement SubtreeReplacement) EntryOrdinal() uint32

func (SubtreeReplacement) Graph 

func (replacement SubtreeReplacement) Graph() mutationir.Graph

type TransactionAdapter 

type TransactionAdapter struct {
	Expand   func(context.Context, ExpansionRequest) (RuntimeExpansion, error)
	Apply    func(context.Context, ApplyRequest) (ApplyResult, error)
	Verify   func(context.Context, AppliedNode) error
	Commit   func(context.Context) error
	Rollback func(context.Context) error
}

TransactionAdapter is the explicit integration seam for runtime. Its callbacks normally delegate to:

  • relation expansion/locking SQL for Expand;
  • the P4-D scalar kernel for single-row Apply calls;
  • the bounded batch kernel for updateMany/deleteMany;
  • the upsert kernel for branch selection; and
  • transaction-local hook/result verification for Verify.

Commit and Rollback remain runtime-owned so the nested package cannot escape or replace a caller-supplied transaction.

func (TransactionAdapter) ApplyNested 

func (adapter TransactionAdapter) ApplyNested(ctx context.Context, request ApplyRequest) (ApplyResult, error)

func (TransactionAdapter) CommitNested 

func (adapter TransactionAdapter) CommitNested(ctx context.Context) error

func (TransactionAdapter) ExpandNested 

func (adapter TransactionAdapter) ExpandNested(ctx context.Context, request ExpansionRequest) (RuntimeExpansion, error)

func (TransactionAdapter) RollbackNested 

func (adapter TransactionAdapter) RollbackNested(ctx context.Context) error

func (TransactionAdapter) VerifyNested 

func (adapter TransactionAdapter) VerifyNested(ctx context.Context, applied AppliedNode) error

type TransformRequest 

type TransformRequest struct {
	// contains filtered or unexported fields
}

func (TransformRequest) Node 

func (request TransformRequest) Node() mutationir.Node

func (TransformRequest) Parent 

func (request TransformRequest) Parent() (AppliedNode, bool)

func (TransformRequest) RelationAnchor 

func (request TransformRequest) RelationAnchor() (AppliedNode, bool)

func (TransformRequest) Stage 

func (request TransformRequest) Stage() TransformStage

func (TransformRequest) Work 

func (request TransformRequest) Work() (RuntimeWork, bool)

type TransformStage 

type TransformStage uint8
const (
	TransformPreExpand TransformStage = iota + 1
	TransformPostExpand
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.