Help us shape the future of Go! Take the 2026 Go Developer Survey

b5dml

package
v1.9.0 Latest Latest
Warning

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

 Go to latest Published: Oct 18, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package b5dml contains the feature-off B5 S5a DML authorization, statement semantics, closure, and native-BEGIN cleanup contracts.

This package is intentionally independent from columnauth. columnauth is a SELECT-only output/reference and mask contract; a write path must never consume its ProtectionPlan. b5dml also has no database driver, migration, feature flag, or production entry-point integration. The PostgreSQL binder and persisted policy schema belong to S5b and S1b respectively.

Index

Constants

View Source 
const (
	ActionUnknown = b5.ActionUnknown
	ActionInsert  = b5.ActionInsert
	ActionUpdate  = b5.ActionUpdate
	ActionDelete  = b5.ActionDelete
)
View Source 
const (
	GrantEffectUnknown = b5.GrantEffectUnknown
	GrantAllow         = b5.GrantAllow
	GrantDeny          = b5.GrantDeny
)
View Source 
const (
	GrantElementUnknown = b5.GrantElementUnknown
	GrantAction         = b5.GrantElementAction
	GrantWriteTarget    = b5.GrantElementWriteTarget
	GrantReference      = b5.GrantElementReference
)
View Source 
const (
	FrozenClosureNegativeEntries = 27
	FrozenClosureDialectCells    = FrozenClosureNegativeEntries * 2
)

FrozenClosureNegativeEntries is the reviewed PostgreSQL row count. The same rows are exercised for MySQL, yielding FrozenClosureDialectCells cells.

View Source 
const (
	// BinderABI is the reviewed name reserved for the future PostgreSQL DML
	// binder implemented by the isolated, feature-off S5b businessdb adapter.
	BinderABI = "agentsql-binder-dml-1"

	// AuthorizationContractSchema identifies this non-persisted S5a canonical
	// contract. S1b must assign the formal proof and storage schema versions.
	AuthorizationContractSchema = "agentsql.b5.dml-authorization-contract.s5a.v1"
	BeginCleanupProofSchema     = b5.BeginCleanupProofSchemaID
	BeginCleanupProofVersion    = b5.BeginCleanupProofVersion

	// GrantSchemaDecision records the reviewed conclusion without pretending
	// that S5a has created the S1b persistence schema.
	GrantSchemaDecision = b5.DMLGrantProofSchemaID
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Action 

type Action = b5.DMLAction

type ApprovalDisposition 

type ApprovalDisposition string
const ApprovalConsumedBeginFailed ApprovalDisposition = "consumed_begin_failed"

type AssignmentKind 

type AssignmentKind uint8
const (
	AssignmentUnknown AssignmentKind = iota
	AssignmentExplicitValue
	AssignmentExplicitDefault
	AssignmentOmitted
)

type AuthorizationDecision 

type AuthorizationDecision struct {
	Schema        string
	SchemaVersion uint16
	// contains filtered or unexported fields
}

func Authorize 

func Authorize(input AuthorizationInput) AuthorizationDecision

Authorize implements an independent DML lattice. The order is compatible with B2's fail-closed segments, but DML has no output grant and no mask meet: preliminary deny -> unsupported -> reserved target -> action deny/missing -> identity/closure -> write deny/missing -> reference-form/deny/missing -> allow. Within an element, deny is absorbing; allows from multiple policies union.

func (AuthorizationDecision) Allowed 

func (decision AuthorizationDecision) Allowed() bool

func (AuthorizationDecision) Digest 

func (decision AuthorizationDecision) Digest() string

func (AuthorizationDecision) Reason 

func (decision AuthorizationDecision) Reason() AuthorizationReason

func (AuthorizationDecision) Verify 

func (decision AuthorizationDecision) Verify(input AuthorizationInput) bool

type AuthorizationInput 

type AuthorizationInput struct {
	PrincipalID           string
	DatasourceID          string
	Dialect               Dialect
	CurrentServerMajor    int
	Action                Action
	Target                RelationIdentity
	Writes                []WriteTarget
	References            []Reference
	Policies              []Policy
	PreliminaryAllowed    bool
	DatasourceSupported   bool
	ReservedTarget        bool
	CatalogConsistent     bool
	ClosureProven         bool
	PolicySnapshotDigest  string
	CatalogSnapshotDigest string
	ClosureDigest         string
	PlanDigest            string
	Attestations          []BinderAttestation
}

type AuthorizationReason 

type AuthorizationReason string
const (
	ReasonAllow                    AuthorizationReason = "ALLOW"
	ReasonPreliminaryDenied        AuthorizationReason = "DML_PRELIMINARY_DENIED"
	ReasonDialectUnsupported       AuthorizationReason = "DML_DIALECT_UNSUPPORTED"
	ReasonReservedTarget           AuthorizationReason = "DML_RESERVED_TARGET_DENIED"
	ReasonActionDenied             AuthorizationReason = "DML_ACTION_DENIED"
	ReasonActionGrantMissing       AuthorizationReason = "DML_ACTION_GRANT_MISSING"
	ReasonIdentityUnproven         AuthorizationReason = "DML_IDENTITY_UNPROVEN"
	ReasonClosureUnproven          AuthorizationReason = "DML_CLOSURE_UNPROVEN"
	ReasonWriteTargetDenied        AuthorizationReason = "DML_WRITE_TARGET_DENIED"
	ReasonWriteTargetGrantMissing  AuthorizationReason = "DML_WRITE_TARGET_GRANT_MISSING"
	ReasonReferenceFormUnsupported AuthorizationReason = "DML_REFERENCE_FORM_UNSUPPORTED"
	ReasonReferenceDenied          AuthorizationReason = "DML_REFERENCE_DENIED"
	ReasonReferenceGrantMissing    AuthorizationReason = "DML_REFERENCE_GRANT_MISSING"
)

type BeginAttemptEvidence 

type BeginAttemptEvidence struct {
	Write             b5terminal.WriteEvidence
	Reply             BeginReplyKind
	Correlation       b5terminal.CorrelationStrength
	ServerStatus      b5terminal.ServerTxState
	ProtocolUntouched bool
}

type BeginCleanupAction 

type BeginCleanupAction uint8
const (
	BeginCleanupNone BeginCleanupAction = iota
	BeginCleanupReleaseUnusedClaim
	BeginCleanupReleaseConnection
	BeginCleanupDiscardConfirmed
	BeginCleanupQuarantine
	BeginCleanupFinishRollback
)

type BeginCleanupDecision 

type BeginCleanupDecision struct {
	Schema        string
	SchemaVersion uint16
	Resource      BeginResourceState
	Action        BeginCleanupAction
	Disposition   b5terminal.ConnectionDisposition
	Approval      ApprovalDisposition
	Attempt       b5terminal.TerminalAttempt
	TerminalOwned bool
}

type BeginMachine 

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

BeginMachine owns the resource-fact state for one consumed begin. Cleanup is idempotent and, for a native transaction, acquires S4a's generation-bound rollback owner exactly once.

func NewBeginMachine 

func NewBeginMachine(transactionGeneration, ownerGeneration uint64, terminal *b5terminal.TerminalOwner) *BeginMachine

func (*BeginMachine) Cleanup 

func (machine *BeginMachine) Cleanup(checks b5terminal.ReleaseChecks, backendAbsenceConfirmed bool) BeginCleanupDecision

func (*BeginMachine) ObserveBegin 

func (machine *BeginMachine) ObserveBegin(evidence BeginAttemptEvidence) bool

func (*BeginMachine) PinConnection 

func (machine *BeginMachine) PinConnection() bool

func (*BeginMachine) ResourceState 

func (machine *BeginMachine) ResourceState() BeginResourceState

type BeginReplyKind 

type BeginReplyKind uint8
const (
	BeginReplyMissing BeginReplyKind = iota
	BeginReplyPositiveACK
	BeginReplyDefinitiveRejection
	BeginReplyUntypedOrMismatched
)

type BeginResourceState 

type BeginResourceState uint8
const (
	BeginNoConnection BeginResourceState = iota
	BeginPinnedNotStarted
	BeginPinnedRejected
	BeginACKLostOrIndeterminate
	BeginNativeBegun
)

type BinderAttestation 

type BinderAttestation struct {
	Mode             BinderAttestationMode
	ServerMajor      int
	ABI              string
	BuildHash        string
	ExtensionHash    string
	NodeManifestHash string
	AllowlistHash    string
}

BinderAttestation is independently built and hashed for one PostgreSQL major. Native mode requires the complete PG14--18 artifact set. Catalog closed mode instead requires exactly one embedded grammar/query-pack attestation bound to the current server major.

type BinderAttestationMode added in v0.5.0 

type BinderAttestationMode string
const (
	BinderAttestationNative        BinderAttestationMode = "NATIVE_C_V1"
	BinderAttestationCatalogClosed BinderAttestationMode = "CATALOG_CLOSED_V1"
)

type ClosureDecision 

type ClosureDecision struct {
	Allowed bool
	Reason  ClosureReason
}

func CheckClosure 

func CheckClosure(dialect Dialect, shape StatementShape, findings []ClosureFinding) ClosureDecision

CheckClosure is deliberately a negative v0.4 contract. An empty finding set for a simple PostgreSQL statement may proceed to authorization. Every known implicit object is rejected until S5b supplies a major-specific closed ABI. MySQL is unconditionally unsupported and must acquire no business connection.

type ClosureFinding 

type ClosureFinding struct {
	Kind       ClosureKind
	Owner      RelationIdentity
	Dependency RelationIdentity
	InManifest bool
}

type ClosureKind 

type ClosureKind uint8
const (
	ClosureUnknown ClosureKind = iota
	ClosureTriggerWriteOutsideManifest
	ClosureTrigger
	ClosureForeignKeyRead
	ClosureForeignKeyCascadeWrite
	ClosureCheckConstraintRead
	ClosureUniqueConstraintRead
	ClosureExclusionConstraintRead
	ClosureRule
	ClosureView
	ClosurePartitionRouting
	ClosurePartitionChild
	ClosureUserDefinedFunction
	ClosureRowLevelSecurity
	ClosureDefaultExpression
	ClosureIdentitySequence
	ClosureGeneratedExpression
	ClosureExpressionIndex
	ClosurePartialIndexPredicate
	ClosureDomainOrCoercion
)

type ClosureReason 

type ClosureReason string
const (
	ClosureAllowed             ClosureReason = "DML_CLOSURE_ALLOWED"
	ClosureDialectUnsupported  ClosureReason = "DML_DIALECT_UNSUPPORTED"
	ClosureComplexDML          ClosureReason = "DML_COMPLEX_SHAPE_UNSUPPORTED"
	ClosureImplicitUnsupported ClosureReason = "DML_IMPLICIT_OBJECT_UNSUPPORTED"
	ClosureManifestIncomplete  ClosureReason = "DML_CLOSURE_MANIFEST_INCOMPLETE"
)

type ColumnIdentity 

type ColumnIdentity struct {
	Relation     RelationIdentity
	Attnum       int16
	Name         string
	TypeOID      uint32
	TypeModifier int32
	CollationOID uint32
}

ColumnIdentity binds an attnum to its relation and type identity. Positive attnums are ordinary user columns, zero is PostgreSQL's whole-row Var, and negative attnums are system columns. The latter two are representable as references but are rejected by the v0.4 contract.

type Dialect 

type Dialect uint8
const (
	DialectUnknown Dialect = iota
	DialectPostgreSQL
	DialectMySQL
)

type Grant 

type Grant struct {
	Element       GrantElement
	Action        Action
	Relation      RelationIdentity
	WriteKind     WriteTargetKind
	Column        ColumnIdentity
	ReferenceKind ReferenceKind
}

Grant is an S5a in-memory contract, not the persisted S1b schema. Every selector is exact and catalog-bound. Empty names and wildcard OIDs are not representable.

type GrantEffect 

type GrantEffect = b5.GrantEffect

type GrantElement 

type GrantElement = b5.GrantElement

type InsertColumnFact 

type InsertColumnFact struct {
	Column       ColumnIdentity
	Assignment   AssignmentKind
	HasDefault   bool
	Identity     bool
	Generated    bool
	UsesSequence bool
}

InsertColumnFact is one live target-table user column. The binder must emit every column, including omitted columns, so authorization cannot confuse an omitted implicit NULL with "not written".

type Policy 

type Policy struct {
	ID           string
	Revision     uint64
	PrincipalID  string
	DatasourceID string
	Effect       GrantEffect
	Grants       []Grant
}

type Reference 

type Reference struct {
	Kind       ReferenceKind
	Site       ReferenceSite
	Relation   RelationIdentity
	Column     ColumnIdentity
	SystemName string
}

func ColumnReference 

func ColumnReference(column ColumnIdentity, site ReferenceSite) Reference

type ReferenceKind 

type ReferenceKind uint8
const (
	ReferenceUnknown ReferenceKind = iota
	ReferenceColumn
	ReferenceWholeRow
	// ReferenceRowCount represents count(table_alias). count(*) does not carry
	// a relation composite value and is not represented by this kind.
	ReferenceRowCount
	ReferenceRecord
	ReferenceComposite
	ReferenceSystemColumn
)

type ReferenceSite 

type ReferenceSite uint8
const (
	ReferenceSiteUnknown ReferenceSite = iota
	ReferenceWhere
	ReferenceJoin
	ReferenceUsing
	ReferenceExpression
	ReferenceSubquery
	ReferenceForeignKey
	ReferenceConstraint
	ReferenceInternalRead
	ReferenceConflictCheck
	ReferenceReturning
)

type RelationIdentity 

type RelationIdentity struct {
	DatasourceID       string
	DatabaseOID        uint32
	RelationOID        uint32
	RelationKind       byte
	Schema             string
	Name               string
	CatalogFingerprint string
}

RelationIdentity is authority-bearing only as a complete catalog identity. Schema and Name are included for audit readability but never replace OIDs and CatalogFingerprint.

type StatementDecision 

type StatementDecision struct {
	Allowed    bool
	Reason     StatementReason
	Writes     []WriteTarget
	References []Reference
}

func AnalyzeStatement 

func AnalyzeStatement(facts StatementFacts) StatementDecision

AnalyzeStatement freezes statement meaning but does not parse SQL. Its input is the future binder's typed output. For UPDATE FROM and DELETE USING, the split is retained in the returned decision for audit/golden tests even though the v0.4 shape is rejected before authorization or execution.

type StatementFacts 

type StatementFacts struct {
	Dialect       Dialect
	Action        Action
	Shape         StatementShape
	Target        RelationIdentity
	Writes        []WriteTarget
	References    []Reference
	InsertColumns []InsertColumnFact
	Returning     bool
}

type StatementReason 

type StatementReason string
const (
	StatementAllowed                 StatementReason = "DML_STATEMENT_ALLOWED"
	StatementDialectUnsupported      StatementReason = "DML_DIALECT_UNSUPPORTED"
	StatementActionUnsupported       StatementReason = "DML_ACTION_UNSUPPORTED"
	StatementReturningUnsupported    StatementReason = "DML_RETURNING_UNSUPPORTED"
	StatementComplexShapeUnsupported StatementReason = "DML_COMPLEX_SHAPE_UNSUPPORTED"
	StatementIdentityIncomplete      StatementReason = "DML_STATEMENT_IDENTITY_INCOMPLETE"
	StatementDefaultUnsupported      StatementReason = "DML_DEFAULT_UNSUPPORTED"
	StatementGeneratedUnsupported    StatementReason = "DML_GENERATED_UNSUPPORTED"
	StatementIdentityUnsupported     StatementReason = "DML_IDENTITY_COLUMN_UNSUPPORTED"
	StatementSequenceUnsupported     StatementReason = "DML_SEQUENCE_UNSUPPORTED"
	StatementWriteSetInvalid         StatementReason = "DML_WRITE_SET_INVALID"
)

type StatementShape 

type StatementShape uint8
const (
	ShapeUnknown StatementShape = iota
	ShapeSimple
	ShapeUpdateFrom
	ShapeDeleteUsing
	ShapeInsertSelect
	ShapeUpsert
	ShapeMerge
	ShapeCTE
	ShapeWritableCTE
	ShapeDMLSubquery
)

type WriteSource 

type WriteSource uint8
const (
	WriteSourceUnknown WriteSource = iota
	WriteSourceExplicit
	WriteSourceImplicitNull
)

type WriteTarget 

type WriteTarget struct {
	Kind     WriteTargetKind
	Relation RelationIdentity
	Column   ColumnIdentity
	Source   WriteSource
}

func ColumnWrite 

func ColumnWrite(column ColumnIdentity, source WriteSource) WriteTarget

func RowDelete 

func RowDelete(relation RelationIdentity) WriteTarget

type WriteTargetKind 

type WriteTargetKind uint8
const (
	WriteTargetUnknown WriteTargetKind = iota
	WriteTargetColumn
	// WriteTargetRow is the single relation-level target required by DELETE.
	// DELETE does not manufacture a write to every column.
	WriteTargetRow
)

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.