SEAM, defined.
The shared vocabulary for SEAM. Curated from Matthew’s working glossary; cross-referenced where Canvas and SEAM use different names for the same concept. Anchor-linkable per term.
Concepts
Intelligence layer
The governed view sitting between AI agents and the data sources they query. Resolves what a question means against a model before any data is fetched. SEAM is the intelligence layer between your AI and your data.
Intelligence model
The specific configuration that represents your organisation's intelligence layer. The set of YAML definitions (metrics, entities, connections, resources) that govern what your data means. What seam init scaffolds and what Canvas helps you build.
SEAM Framework
The open-source half of SEAM, distributed via npm under Apache-2.0. Comprises @measurelab/seam-cli (the binary) and @measurelab/seam-core (the schema standard, loader, validator, compiler and resolver). Pairs with SEAM Runtime.
SEAM Runtime
The Measurelab-managed half of SEAM. The MCP server that runs in front of agents in production: multi-tenant OAuth, audit logging to BigQuery, downstream MCP proxying, Git-sync from your repository. Not distributed; runs only as part of the Measurelab Cloud engagement.
Governance
The discipline of ensuring agent answers are consistent, auditable and aligned with the organisation's authoritative definitions. SEAM provides governance by intercepting agent queries, resolving them through the model and injecting the relevant context into the response.
Definitions
Metric
A quantifiable business measurement (e.g. monthly_revenue). Carries canonical_source, fallback_sources, context-specific definitions, entity_mapping, governance_status, review_cadence and ai_context. The primary unit of governance in SEAM.
Entity
A business object identified differently across systems (e.g. customer, employee). Defines how the entity appears in each system with identifier, authority and known_gaps, plus resolution rules for cross-system mapping.
Connection
A downstream MCP server or API the runtime can reach. Carries transport config (stdio or HTTP) and governance metadata (authority, refresh, enforcement). The canonical term in SEAM; Canvas calls these “Sources” in the UI for workshop clarity but YAML export uses connection:.
Resource
A discrete governed asset from a connection (e.g. a Slack channel, a GA4 stream, a BigQuery dataset). Has status, governance_status, review_cadence, related_resources, profile (source-specific metadata) and audited_at.
CLI tool
A local CLI binary (gcloud, bq, gh, aws) exposed as governed MCP tools. Each safe-to-allowlist command becomes {cli}__{command}, callable by agents through SEAM. Auth is either shared (server-side credentials) or per-user OAuth. Schema: cli: root key. Distinct from the SEAM CLI (the seam binary you install from npm).
Definition file
A YAML file with one root key (metric:, entity:, connection:, resource:, cli:). Validated against JSON schemas. Supports ${VAR} placeholders for secrets in connection fields.
seam.config.yaml
Project-level configuration file. Defines project name, version, definition paths, defaults (owner, review_cadence) and user-defined governance enums (governance_statuses, review_cadences, source_types, authority_levels).
Compilation
Compile
The process of loading, validating and indexing all definitions into a manifest. Produced by seam compile via the core compiler.
Manifest
The compiled output of all definitions. Contains indexed metrics, entities, connections, resources and cross-references. Generated by compile() and consumed at runtime for resolution and governance.
Cross-references
Bidirectional mappings in the manifest: metric_to_sources, source_to_metrics, entity_to_sources, resource_to_source, source_to_resources. Enable lineage tracing across the model.
Validate
Two-layer process: JSON schema validation against the published schemas, then semantic checks for cross-references, required fields and enum warnings. Produces a validation report.
Resolution
Resolve
Fuzzy-match a query (tool name or natural language) against metric and entity definitions. Returns a result with governed status, name, source, applicable definition, confidence score, fallback sources and entity mappings.
Lookup
Browse or search definitions by type. Used to enumerate metrics, entities, connections and resources.
Audit
Record and query governance decisions. Each audit entry includes timestamp, tool, args, governance context, success/error and latency. Available via seam__audit in the runtime; full BigQuery audit pipeline is part of the Measurelab-managed runtime.
Audit ID
Unique identifier for each resolved query. Format: resolve-YYYY-MM-DD-{3-char-hex}. Used to trace governance decisions back to specific resolutions.
Confidence score
Numeric 0 to 100 match score from the resolver. Exact match = 100, substring = 80, word overlap = 60 to 50; description and synonyms are weighted (description ×0.5, synonyms ×0.7).
Confidence level
Categorical match strength derived from the confidence score: high (≥80), medium (≥50), low (≥20), none (<20).
Governed
A query that matched a metric or entity definition and received injected governance context. Recorded as a boolean flag in audit and resolve responses.
Ungoverned
A query that did not match any definition. The resolver returns a confidence score and a reason (e.g. “No governed definition found”).
Governance
Canonical source
The primary authoritative source for a metric. Always queried unless unavailable; fallback sources are tried in order if it is.
Fallback sources
Priority-ordered list of alternative sources to query if the canonical source is unavailable. Included in the governance context returned by the resolver.
Context (metric context)
A context-specific definition override for a metric. For example, a sales context might define monthly_revenue as bookings, while a finance context defines it as recognised revenue. Each context specifies definition, source and optional notes.
Availability
How a source can be accessed: api, mcp, warehouse_replica, with an optional warehouse_staleness figure. Guides downstream query routing.
Refresh
Data freshness cadence for a source or connection (e.g. real-time, hourly, daily, weekly). Included in the governance context returned to the agent.
Enforcement
How strictly governance is applied to a connection or source: observe (log only), advise (include context, don’t block) or enforce (block or flag if requirements aren’t met).
Governance status
Maturity stage of a definition: draft, review, approved, deprecated. User-extendable in seam.config.yaml.
Review cadence
How often a definition must be reviewed: weekly, monthly, quarterly, yearly. User-extendable in seam.config.yaml.
Entity mapping
Maps source names to entity identifier fields (e.g. {finance_system: contact_id, crm: company_id}). Tells the resolver how to find entities in each connected system.
Temporal
Version history of metric definition changes. Each entry has an effective_from date and a change description. The resolver includes a temporal note in its response if applicable.
Definition format
AI context
OSI-compatible metadata block on any definition. Contains synonyms (boost resolver matching, ×0.7), instructions (guidance for the AI) and examples (discovery hints).
Synonyms
Alternative terms an agent might use when referring to a metric or entity. Part of ai_context. The resolver weights synonym matches at 0.7.
Groups
Cross-definition filtering array (e.g. [marketing, finance, product]). Optional on all definition types. Used for organisation and access control.
CLI commands
seam init
Scaffold a new SEAM project with directories, seam.config.yaml and example definitions.
seam validate
Load and validate definitions against JSON schemas and semantic rules. Returns a validation report.
seam compile
Load, validate and compile all definitions into a manifest.json.
seam resolve
Fuzzy-match a query against the compiled manifest. Returns the matched definition with governance context.
Native MCP tools
seam__resolve
MCP tool exposed by the runtime. Resolves a natural-language or tool-name query against the governance layer and returns context.
seam__lookup
MCP tool exposed by the runtime. Browses and searches definitions by type.
seam__audit
MCP tool exposed by the runtime. Queries the audit log for governance decisions and tool call history.
Architecture
Upstream
The client calling SEAM (Claude, Claude Code, the web UI). SEAM acts as an MCP server to upstream clients.
Downstream
A remote MCP server that SEAM connects to and proxies tools from. Discovered tools are namespaced and exposed back through SEAM.
Dual-role
SEAM’s architecture as both an MCP server (receives calls from upstream clients) and an MCP client (proxies calls to downstream servers).
Per-user OAuth
Auth mode where each user authenticates individually with their own OAuth tokens. Connection is marked auth.type: per-user-oauth. Tokens stored encrypted per user.
Git-sync
Automatic synchronisation of definitions from a Git repository. The runtime polls on interval, detects new, updated or deleted files and reloads definitions accordingly.
Standards
MCP
Model Context Protocol. The standard SEAM implements for both its server interface (receiving calls from Claude) and its client interface (connecting to downstream tools). Anthropic’s open protocol for connecting LLMs to tools and data. SDK: @modelcontextprotocol/sdk.
OSI
Open Semantic Interchange. Vendor-neutral semantic layer specification backed by Snowflake, dbt Labs, Salesforce and Databricks. SEAM’s definition format is OSI-aligned with extensions for distributed governance, entity resolution, context-specific definitions and temporal versioning.
Canvas terms
Canvas
The SEAM Canvas application. Browser-based React tool for visual governance facilitation. Renders an intelligence layer as an interactive swimlane diagram with nodes for connections, entities and metrics. Used live in workshops to assign canonical sources, write definitions and push back to a SEAM repository.
Shadow node
A Canvas node representing something that exists in practice but isn’t yet formally governed. Surfaced from audit log queries that returned governed: false. Can be promoted to a governed metric or connection.
Push to SEAM
The Canvas action that writes a governed metric definition as a YAML file into the connected SEAM Git repository. Triggers the runtime’s git-sync, making the metric resolvable on next query.