seam-sdk

Compile-time contract library for ONT seam-family operators

What it is

seam-sdk is a pure Go library. It has no deployable binary and is never installed to a cluster. Importing it and implementing SeamOperator is the compile-time gate for membership in the seam operator family. An operator binary that does not satisfy SeamOperator cannot be registered with the seam domain controller.

This library prevents operators from defining their own label keys, condition strings, or annotation keys. It enforces a shared vocabulary at compile time. Every constant in every package in this library is the authoritative definition for the entire platform. New values require a PR to this repository and Platform Governor review.

Module: github.com/ontai-dev/seam-sdk

SeamOperator interface

Every ONT operator implements SeamOperator from package operator. The interface has seven methods divided into two logical groups.

type SeamOperator interface {
    // Identity group
    OperatorName() string
    MembershipCRName() string
    ReadyConditionType() string

    // Governance metadata group
    Domain() string
    Subdomain() string
    ConditionTypes() []string
    LineageLabelSchema() map[string]string
}

Identity group -- declare who the operator is and how it registers its presence:

• OperatorName() -- unique, stable name within the seam domain. Used as the subject name on SeamMembership CRs and as the value of the seam.ontai.dev/managed-by label on all resources this operator creates. Examples: "platform", "guardian", "dispatcher", "conductor", "seam".
• MembershipCRName() -- name of the SeamMembership CR declared on startup. Convention: "seam-<operator-name>". Created idempotently before any reconciliation begins.
• ReadyConditionType() -- condition type written to the operator's primary CR when SeamMembership is declared and RBACProfile is active. Gates all other reconciliation. INV-003.

Governance metadata group -- encode the operator's CRD scope, condition vocabulary, and lineage label contract:

• Domain() -- API group of this operator's primary CRDs. Used in RBAC rules, CRD spec, and admission webhook config. Examples: "seam.ontai.dev", "guardian.ontai.dev", "platform.ontai.dev".
• Subdomain() -- functional scope within the API group. Partitions operators that share a group. Examples: "core", "infrastructure", "rbac", "pack", "conductor".
• ConditionTypes() -- complete set of condition type strings this operator writes to its primary operational CRs. Every string in this slice must be defined as a constant in seam-sdk/conditions. Must include at minimum conditions.ConditionReady. SDK-INV-002.
• LineageLabelSchema() -- label key-value pairs stamped on every resource this operator creates. Keys must be constants from seam-sdk/labels. Fixed-at-compile-time values are filled in by this method; dynamic values (resource names filled at reconcile time) are represented as empty string in the schema. SDK-INV-002.

Packages

Package	Description
operator	Defines SeamOperator, the compile-time interface every ONT operator must satisfy.
labels	Standard lineage label key constants (seam.ontai.dev/*) set on every CR created or managed by a seam-family controller.
conditions	Standard condition type constants (Ready, SeamMembershipProvisioned, RBACProfileActive, Reconciling, Degraded, Failed) written by all seam operators to their primary CRs.
annotations	Standard annotation key constants for admission control, governance, lineage cross-references, and pack delivery.
validation	Shared CEL validation rule fragment constants for embedding in CRD x-kubernetes-validations. All CEL rules in seam-family CRDs must use fragments from this package.
scaffold	Compiler subcommand logic for generating operator scaffolds pre-wired with seam-sdk imports. Two kinds: seam-domain and ont-app. Compiler-only; never imported by Conductor.

Usage

Import path:

github.com/ontai-dev/seam-sdk

Example implementation of SeamOperator in an operator's main package:

import (
    "github.com/ontai-dev/seam-sdk/conditions"
    "github.com/ontai-dev/seam-sdk/labels"
    "github.com/ontai-dev/seam-sdk/operator"
)

type PlatformOperator struct{}

func (o *PlatformOperator) OperatorName() string       { return "platform" }
func (o *PlatformOperator) MembershipCRName() string   { return "seam-platform" }
func (o *PlatformOperator) ReadyConditionType() string { return conditions.ConditionReady }
func (o *PlatformOperator) Domain() string             { return "seam.ontai.dev" }
func (o *PlatformOperator) Subdomain() string          { return "infrastructure" }
func (o *PlatformOperator) ConditionTypes() []string {
    return []string{
        conditions.ConditionReady,
        conditions.ConditionReconciling,
        conditions.ConditionDegraded,
    }
}
func (o *PlatformOperator) LineageLabelSchema() map[string]string {
    return map[string]string{
        labels.LabelManagedBy:              "platform",
        labels.LabelRootDeclarationKind:    "",
        labels.LabelRootDeclarationName:    "",
        labels.LabelRootDeclarationNamespace: "",
    }
}

// Compile-time assertion. If PlatformOperator does not satisfy SeamOperator,
// this line produces a build error.
var _ operator.SeamOperator = &PlatformOperator{}

Use label constants instead of inline strings:

import "github.com/ontai-dev/seam-sdk/labels"

resource.Labels[labels.LabelManagedBy] = "platform"
resource.Labels[labels.LabelRootDeclarationKind] = "TalosCluster"

Use condition type constants instead of inline strings:

import "github.com/ontai-dev/seam-sdk/conditions"

meta.SetStatusCondition(&cr.Status.Conditions, metav1.Condition{
    Type:   conditions.ConditionReady,
    Status: metav1.ConditionTrue,
})

Building

go build ./...

---

seam-sdk - Seam Operator Contract Library / Apache License, Version 2.0