Package Composition and Lifecycle

This reference defines runtime installation, compatibility, composition and removal. The Development Environment and SDK create package definitions; publication and deployment remain separate operations.

2. Composability Model

flowchart TB
    K["Minimal Telynt kernel"] --> C["Composition engine"]
    R["Private and Marketplace registries"] --> C
    C --> L["Resolved environment lock"]
    L --> D["Data models"]
    L --> W["Workflows"]
    L --> A["Agents and models"]
    L --> X["Tools and connectors"]
    L --> P["Policies and evaluations"]
    L --> I["Interfaces and navigation"]

The composition engine resolves package versions, capabilities, dependencies, conflicts, schemas, migrations, permissions, resource requirements, interface slots, evaluation gates, and rollback behavior before producing an immutable environment lock.

3. Minimal Non-Removable Kernel

Full composability requires a small stable kernel. Removing these concepts would prevent the platform from identifying a tenant, authorizing a request, understanding a package, executing a process, or reconstructing a change.

The kernel owns only:

• Tenant and OrganizationReference;
• Principal, ServiceIdentity, and RoleBinding;
• Package, PackageVersion, and Capability;
• Installation, Entitlement, and Environment;
• ChangeSet, EnvironmentLock, and Approval;
• WorkflowRun, AgentRun, and ToolRun;
• PolicyDecision and SecretReference;
• ArtifactReference and AuditEvent.

Customer, account, opportunity, meeting, project, contract, SOW, case, requirement, and other business master objects do not belong to the kernel. They are supplied by installable DataModelPackage artifacts.

4. Package Types

Every package is an immutable OCI artifact with a globally unique namespaced identifier, semantic version, digest, publisher, ownership scope, license, signature, provenance, bill of materials, compatibility metadata, requested capabilities, evaluation attestations, and lifecycle policy. OCI supports content-addressed artifacts other than container images, which allows Telynt to distribute schemas, policies, interfaces, models, and bundles through the same registry contract. See the OCI image and artifact specification and ORAS artifact model.

5. ConfigurationBundle as the Marketplace Module

A Marketplace item presented as a module is technically a signed ConfigurationBundle. A module can deliver an entire business capability rather than requiring the buyer to assemble individual artifacts.

schema_version: configuration-bundle.v2
bundle_id: publisher.supplier-risk-management
version: 2.3.0
publisher: publisher
requires:
  platform_api: ">=1.4 <2.0"
  capabilities:
    - entity.supplier@^2
    - workflow.human-approval@^1
provides:
  - supplier-risk-analysis@2
  - supplier-risk-interface@2
conflicts:
  - legacy-supplier-risk@<3
packages:
  data_models:
    - publisher.supplier-model@2.1.0
  agents:
    - publisher.supplier-risk-agent@3.0.0
  workflows:
    - publisher.supplier-review@2.3.0
  interfaces:
    - publisher.supplier-risk-ui@2.3.0
uninstall:
  default_data_disposition: ARCHIVE_AND_RETAIN
  active_run_policy: DRAIN

6. Bundle Relationships and Enrichment

A bundle can enrich another bundle without copying or modifying it. The manifest uses explicit relationships:

Direct mutation of another publisher's package is prohibited. Enrichment remains a separate signed package with its own version, license, provenance, evidence, evaluations, activation, and rollback.

6.1 Industry-Solution Composition

An IndustrySolution is the higher-order Marketplace artifact used when multiple capability bundles jointly cover the standard needs of a sector. It records required, default-active, restricted, recommended, optional, alternative, and conflicting bundle relationships. Customer changes are stored in a separate CustomerConfiguration; they never fork or overwrite the publisher's Industry Solution. The implemented hierarchy, Marketplace behavior, and Technology Consulting & Delivery reference composition are specified in the Industry Solution Composition Model.

6.2 Extension Points

A bundle exposes typed extension points such as:

• meeting.classifiers;
• meeting.finding-producers;
• finding.taxonomies;
• finding.enrichment-fields;
• workflow.post-analysis;
• meeting.tabs;
• overview.widgets;
• report.sections;
• search.index-projections;
• entity.project.extensions;
• policy.review-profiles.

An extension point declares accepted schemas, cardinality, ordering, conflict rules, permissions, performance budgets, evaluation requirements, and interface placement.

6.3 Example: Additional Meeting Knowledge

The default Meeting Intelligence bundle publishes the transcript, topics, participants, and meeting.analysis_requested event. An Engineering Architecture Enrichment bundle can then:

1. require the meeting and finding capabilities;
2. contribute an engineering-classification agent to meeting.finding-producers;
3. add TechnicalDecision, ArchitectureRisk, and Requirement types through a DataModelPackage;
4. publish its own evidence-backed findings under its namespace;
5. add filters, labels, widgets, and report sections to declared interface slots;
6. add a post-analysis workflow without changing the base workflow;
7. remain independently removable and rollbackable.

The base meeting artifacts remain unchanged. The composed view displays both base and enrichment results with separate provenance.

7. Data-Model Composition

7.1 Logical Model

Each DataModelPackage declares:

• namespaced entity and value-object types;
• fields, validation, defaults, sensitivity, and localization;
• typed relationships and temporal validity;
• commands, queries, and domain events;
• ownership and extension points;
• PostgreSQL projections and indexes;
• OpenSearch mappings and search projections;
• retention, export, archival, and deletion rules;
• forward, backward, and uninstall migrations.

JSON Schema 2020-12 is the canonical payload description and validation format. JSON Schema provides unique schema identifiers, typed constraints, composition, and a broad validation ecosystem. JSON Schema documentation

CUE validates cross-package constraints, configuration composition, and compatible schema intersections before the compiler emits concrete JSON, YAML, SQL migration plans, API contracts, and index mappings. CUE configuration model

7.2 Physical Model

Telynt does not use an unrestricted entity-attribute-value database as its primary business store. The model compiler creates:

• namespaced PostgreSQL schemas, tables, columns, constraints, and indexes for stable fields;
• controlled JSONB extension areas for compatible additive fields;
• a typed temporal relationship table for cross-package object links;
• generated repository, API, event, and validation contracts;
• reconstructible OpenSearch projections;
• a derivation graph for affected-artifact invalidation.

Packages reference other packages through logical capabilities, schema URIs, object URNs, and APIs rather than physical table names.

7.3 Data-Model Removal

Removal is not a database cascade. The installation plan provides four explicit outcomes:

1. DISABLE — stop new behavior and hide contributed interfaces while retaining the installation;
2. UNINSTALL_RETAIN_DATA — remove executable and interface contributions but retain readable governed records;
3. ARCHIVE_AND_UNINSTALL — export and archive owned data before removing active projections;
4. PURGE_AFTER_RETENTION — delete only after dependency, legal-hold, retention, and approval checks succeed.

Cross-package references, retained workflow runs, reports, evidence, and audits remain resolvable through historical schema and package metadata.

8. Workflow, Agent, and Model Composition

A workflow is the process definition; agents are reusable capability units invoked by that process. Workflows can also contain deterministic rules, timers, tools, connectors, user tasks, and approvals.

Agents require capabilities rather than hard-coding a model implementation whenever possible:

requires:
  capabilities:
    - llm.reasoning@>=2
    - entity.project@^3
    - tool.document.read@^1

The model gateway resolves the qualified model deployment satisfying llm.reasoning for the tenant, data category, language, latency class, hardware, and policy. A customer can replace the model without modifying every compatible agent.

Workflow extension uses declared hooks and typed artifacts. An enrichment bundle can subscribe to an event, add a parallel branch, or contribute a post-processing step, but it cannot insert arbitrary code into another workflow's private state machine.

9. Interface and Navigation Composition

The application shell contains stable extension slots. Every visible destination is compiled from installed InterfacePackage contributions.

Core application shell
+ installed bundle contributions
+ compatible enrichment contributions
+ organization override packages
+ role-aware visibility
+ user preferences
= effective signed-in experience

An interface contribution declares:

• route and route owner;
• parent menu or contextual tab slot;
• label, icon, order, badges, and localization keys;
• page layout and registered components;
• typed queries and commands;
• required capabilities, permissions, feature states, and licenses;
• empty, loading, error, degraded, and restricted behavior;
• responsive and accessibility requirements.

The menu is generated at sign-in from the environment lock, active tenant installations, user entitlements, role and object authorization, feature state, and organization overrides. Removing or disabling a bundle automatically removes its routes, menu items, tabs, widgets, commands, and notification counters.

The default interface path is declarative and uses the Telynt design-system component registry. Exceptional custom visual components use qualified sandboxed Web Components with scoped APIs, content-security policy, and no direct host-state or database access. Web Components provide reusable custom elements and encapsulation through Shadow DOM. Web Components

11. Contextual Marketplace

11.1 Signed Installation Profile

When an authorized user opens the Marketplace from Telynt, OIDC federation associates the session with a specific installation. Telynt supplies a short-lived, signed, permission-scoped InstallationProfile containing only compatibility metadata:

• installation and tenant pseudonymous identifiers;
• Telynt platform and contract API levels;
• installed package IDs, versions, digests, activation states, and entitlements;
• provided and required capabilities;
• schema, protocol, and runtime versions;
• available CPU, accelerator, isolation, and deployment profiles;
• enabled languages and approved residency classes;
• organization-level prohibited capability categories;
• current environment-lock identifier.

The profile contains no customer documents, meetings, transcripts, findings, prompts, secrets, user directory, or business-object instances.

Without an installation-linked session, the Marketplace displays the general catalog. With an authorized linked session, it displays contextual compatibility.

11.2 Marketplace States

Every state includes a human-readable explanation and a machine-readable compatibility report.

12. Compatibility Resolution

The resolver evaluates:

1. semantic version ranges and immutable digests;
2. provided, required, optional, replaced, and conflicting capabilities;
3. platform, schema, API, protocol, runtime, and interface-slot versions;
4. data-model ownership and migration paths;
5. active workflow and feature bindings;
6. permissions, requested tools, network access, and data categories;
7. license, entitlement, publisher, support, and end-of-life terms;
8. language, hardware, performance, residency, and isolation requirements;
9. customer overlays and organization policy;
10. qualification evidence and known security revocations.

A SAT/PubGrub-style dependency solver produces either a complete deterministic solution or an unsatisfied constraint set. It does not choose a partially compatible installation.

Before acceptance, the Marketplace presents an installation plan containing:

• packages added, removed, upgraded, downgraded, retained, or replaced;
• capabilities gained or lost;
• data-model and migration changes;
• routes, menus, screens, widgets, commands, and reports added or removed;
• new identities, permissions, tools, connectors, and external destinations;
• resource, model, accelerator, storage, and expected cost changes;
• evaluation and approval requirements;
• downtime or background-reindex implications;
• rollback target and data-disposition behavior.

13. Installation, Update, and Removal

13.1 Installation and Update

Resolve
-> show plan and permissions
-> accept license
-> verify artifact, signature, provenance and SBOM
-> install in Development
-> qualify in Testing
-> preview and rehearse migration in Staging
-> Production canary
-> activate and monitor

Each stage promotes the same immutable digests. Activation produces a new environment lock and never mutates the prior one.

13.2 Removal

The removal controller:

1. computes dependent packages, routes, workflows, agents, models, data, reports, and entitlements;
2. blocks removal when a required dependency lacks a compatible replacement;
3. stops new triggers and drains, cancels, or migrates active workflows according to policy;
4. applies the selected data disposition;
5. removes effective interface and navigation contributions;
6. preserves retained runs, evidence, reviews, reports, and audit history;
7. qualifies the removal and rollback path in Testing and Staging;
8. creates a new signed Production environment lock.

14. Composition Precedence and Conflict Rules

Composition is deterministic:

1. kernel contracts;
2. required base bundles;
3. compatible enrichment bundles;
4. organization overlay packages;
5. role-aware interface visibility;
6. user display preferences.

Policy does not use permissive override precedence. Deny, segregation, retention, and required-review constraints remain dominant unless an explicitly authorized versioned policy change replaces them. Data-model conflicts fail composition. Interface ordering conflicts use declared priority and stable package identity; two packages cannot own the same canonical route. Findings from different bundles coexist and retain distinct provenance rather than overwriting one another.

15. Acceptance Criteria

1. Every active business capability resolves to signed packages in the current environment lock.
2. Every package declares ownership, version, compatibility, permissions, lifecycle, evaluation, and rollback metadata.
3. Every business master model can be installed, extended, versioned, disabled, archived, and removed through a DataModelPackage lifecycle.
4. Kernel types cannot be shadowed or removed by a package.
5. Every route, menu item, screen, widget, and action resolves to an installed InterfacePackage contribution and an authorization decision.
6. Every workflow resolves all agent, model, tool, data, policy, and interface capabilities before activation.
7. One bundle can enrich another only through declared typed extension points.
8. Enrichment preserves separate package ownership, evidence provenance, evaluation, versioning, and rollback.
9. The Marketplace accurately distinguishes installed, compatible, prerequisite-dependent, conflicting, blocked, deprecated, and revoked modules.
10. Marketplace compatibility uses a signed metadata-only installation profile and never requires business evidence.
11. Every install, update, enrichment, replacement, or removal produces a complete plan and ChangeSet before entering a shared environment.
12. Customer AI-assisted customization creates private package versions and never directly mutates Production or publisher artifacts.
13. Removal preserves every retained historical reference and never silently cascades into unrelated data loss.
14. The previous Production environment lock remains a tested rollback target.
15. An organization can install and operate qualified packages without deploying the Development Environment or SDK in the target runtime.
16. Publishers and customer teams use the same package contracts; private deployments do not require Marketplace publication.
17. Natural-language authoring creates reviewable package drafts. Authoring, publishing and deploying have separate authorization checks and audit events.

Documentation ownership

Every package owns its functional guide, configuration, agents, workflows, models and screen reference. Industry solutions describe their selected composition and cross-package behavior. The platform owns shared enforcement and runtime contracts, not a fixed inventory of business capabilities.