@collective-intelligence/extensions-sdk 0.1.10 → 0.1.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -427,7 +427,7 @@ fieldSemantics: {
427
427
  "/companies": {
428
428
  relation: {
429
429
  targetSchemaFqn: "core.schemas.crm.company",
430
- cardinality: "many",
430
+ cardinality: "many_to_many",
431
431
  maxItems: 20,
432
432
  onDelete: "restrict",
433
433
  display: { fields: [{ field: "name", scope: "data" }] },
@@ -440,8 +440,18 @@ fieldSemantics: {
440
440
  }
441
441
  ```
442
442
 
443
- `cardinality` is `one` or `many`. `maxItems` is an optional positive item limit
444
- of a `many` field; without it the field has no limit. `onDelete` is `clear` or
443
+ `cardinality` describes source-to-target limits, independently of whether an
444
+ inverse field is exposed. One means at most one, not a required link.
445
+
446
+ | Cardinality | Targets per source | Sources per target | Forward / inverse shape |
447
+ | -------------- | ------------------ | ------------------ | ----------------------- |
448
+ | `one_to_one` | At most one | At most one | Scalar / scalar |
449
+ | `one_to_many` | Many | At most one | Array / scalar |
450
+ | `many_to_one` | At most one | Many | Scalar / array |
451
+ | `many_to_many` | Many | Many | Array / array |
452
+
453
+ `maxItems` is an optional positive item limit for `one_to_many` and
454
+ `many_to_many` owners; scalar owners reject it. `onDelete` is `clear` or
445
455
  `restrict`; the platform applies `clear` when it is absent. `display.fields`
446
456
  and `autocomplete.fields` name `{ field, scope: "data" | "entity" }` fields of
447
457
  the target schema; `autocomplete.baseFilters` are ANDed schema-aware filters
@@ -454,6 +464,159 @@ a relation schema. Package deploy resolves `targetSchemaFqn` among the entity
454
464
  schemas of the Organization. The metadata-only `relationFields` declaration
455
465
  is removed; manifest parsing refuses a release that still declares it.
456
466
 
467
+ An optional inverse names the owner by schema FQN and exact top-level RFC 6901
468
+ pointer. For example, Company can expose Contact.company through:
469
+
470
+ ```ts
471
+ fieldSemantics: {
472
+ "/contacts": {
473
+ relation: {
474
+ inverseOf: { schemaFqn: "core.schemas.crm.contact", field: "/company" },
475
+ display: { fields: [{ field: "name", scope: "data" }] }
476
+ }
477
+ }
478
+ }
479
+ ```
480
+
481
+ Inverse declarations accept `inverseOf` and optional `display`; they reject a
482
+ target, cardinality, picker (`autocomplete`), `maxItems`, or delete policy.
483
+ The host resolves the member schema and value shape from the owner. Authors
484
+ omit both forward and inverse properties from their ordinary value schema;
485
+ the host generates read contracts and excludes inverse fields from writes.
486
+ Pair resolution, permissions and database enforcement belong to the host,
487
+ not this portable SDK. Removing an inverse does not change owner constraints.
488
+ The legacy `one` and `many` authoring literals are rejected; migrate them to
489
+ `many_to_one` and `many_to_many`, respectively, to preserve reverse sharing.
490
+
491
+ ### Complete cardinality example
492
+
493
+ These five declarations belong to one package with the declared Directory domain
494
+ (or a dependency supplying it). Person owns every relationship. Passport.holder
495
+ and Asset.owner are scalar inverses; Company.employees and Group.members are
496
+ list inverses. Every inverse is optional: removing it preserves the corresponding
497
+ owner's constraints and links. A local helper repeats ordinary schema settings;
498
+ it is not an additional SDK API.
499
+
500
+ ```ts
501
+ import {
502
+ declareKnowledgeEntitySchema,
503
+ knowledgeRecordSchema,
504
+ type KnowledgeFieldSemantics
505
+ } from "@collective-intelligence/extensions-sdk"
506
+
507
+ // The package also supplies com.acme.domains.directory, or depends on its owner.
508
+ // This local helper only avoids repeating the ordinary schema settings.
509
+ function entity(
510
+ key: string,
511
+ displayName: string,
512
+ fieldSemantics: Readonly<Record<string, KnowledgeFieldSemantics>>
513
+ ) {
514
+ return declareKnowledgeEntitySchema({
515
+ manifest: { fqn: `com.acme.schemas.directory.${key}`, version: "1.0.0" },
516
+ presentation: { displayName },
517
+ definition: {
518
+ domainFqn: "com.acme.domains.directory",
519
+ lifecycle: { deployMode: "upsert", readonly: false },
520
+ schema: knowledgeRecordSchema({
521
+ properties: { name: { type: "string" } }
522
+ }),
523
+ fieldSemantics,
524
+ autocompleteConfiguration: {
525
+ autocompleteFields: [],
526
+ defaultAutocompleteFields: []
527
+ },
528
+ displayNameExpression: null,
529
+ embeddingConfig: null,
530
+ persistFullFieldContributions: false,
531
+ usableAsDocumentScope: false,
532
+ versioningEnabled: null
533
+ }
534
+ })
535
+ }
536
+
537
+ export const Person = entity("person", "Person", {
538
+ "/passport": {
539
+ relation: {
540
+ targetSchemaFqn: "com.acme.schemas.directory.passport",
541
+ cardinality: "one_to_one"
542
+ }
543
+ },
544
+ "/assets": {
545
+ relation: {
546
+ targetSchemaFqn: "com.acme.schemas.directory.asset",
547
+ cardinality: "one_to_many"
548
+ }
549
+ },
550
+ "/company": {
551
+ relation: {
552
+ targetSchemaFqn: "com.acme.schemas.directory.company",
553
+ cardinality: "many_to_one"
554
+ }
555
+ },
556
+ "/groups": {
557
+ relation: {
558
+ targetSchemaFqn: "com.acme.schemas.directory.group",
559
+ cardinality: "many_to_many"
560
+ }
561
+ }
562
+ })
563
+
564
+ export const Passport = entity("passport", "Passport", {
565
+ "/holder": {
566
+ relation: {
567
+ inverseOf: {
568
+ schemaFqn: "com.acme.schemas.directory.person",
569
+ field: "/passport"
570
+ }
571
+ }
572
+ }
573
+ })
574
+ export const Asset = entity("asset", "Asset", {
575
+ "/owner": {
576
+ relation: {
577
+ inverseOf: {
578
+ schemaFqn: "com.acme.schemas.directory.person",
579
+ field: "/assets"
580
+ }
581
+ }
582
+ }
583
+ })
584
+ export const Company = entity("company", "Company", {
585
+ "/employees": {
586
+ relation: {
587
+ inverseOf: {
588
+ schemaFqn: "com.acme.schemas.directory.person",
589
+ field: "/company"
590
+ }
591
+ }
592
+ }
593
+ })
594
+ export const Group = entity("group", "Group", {
595
+ "/members": {
596
+ relation: {
597
+ inverseOf: {
598
+ schemaFqn: "com.acme.schemas.directory.person",
599
+ field: "/groups"
600
+ }
601
+ }
602
+ }
603
+ })
604
+
605
+ // Add these declarations to the existing package's primitives collection.
606
+ export const relationSchemas = [Person, Passport, Asset, Company, Group]
607
+ ```
608
+
609
+ Only Person's forward properties accept writes. For example, `passport` and
610
+ `company` accept an ID or null; `assets` and `groups` accept ID arrays. One means
611
+ at most one, not required participation. Two independent forward declarations
612
+ would create two relationships; use `inverseOf` to expose the same links.
613
+
614
+ See the [relation field operator reference](../../../docs/reference/knowledge-relation-fields.md)
615
+ for SQL enforcement, safe cardinality changes, rollout and read limits. Package
616
+ comparison uses source-owned definitions; the host independently validates the
617
+ resolved inverse runtime shape. Authors never copy generated properties into
618
+ their ordinary schema.
619
+
457
620
  The host rejects `onDelete: "restrict"` for targets with `managedProjection`
458
621
  and for `core.schemas.directory.organization` and
459
622
  `core.schemas.strategy.organization-context`; use `clear` for these targets.
@@ -635,6 +798,42 @@ export const salesGroup = declareOrganizationGroup({
635
798
  The manifest stores the FQN string. A subgroup has no handle; name it by its
636
799
  FQN string, also inside the same package.
637
800
 
801
+ ## Service principal declarations
802
+
803
+ `servicePrincipal` declares one non-human identity with one Organization Role
804
+ and memberships in Groups declared by the same package. `version` is required
805
+ common SDK primitive metadata; it has no default and is independent of the
806
+ package version. `name` becomes the manifest's `displayName`.
807
+
808
+ ```ts
809
+ import {
810
+ declarePackage,
811
+ servicePrincipal
812
+ } from "@collective-intelligence/extensions-sdk"
813
+
814
+ const importer = servicePrincipal({
815
+ fqn: "acme.directory.importer",
816
+ name: "Importer",
817
+ version: "1.0.0",
818
+ organizationRole: "organization_operator",
819
+ groups: [salesGroup, "acme.directory.groups.sales.inside-sales.emea"]
820
+ })
821
+
822
+ export const directory = declarePackage({
823
+ manifest: { fqn: "acme.directory", name: "Directory", version: "1.0.0" },
824
+ components: [salesGroup, importer]
825
+ })
826
+ ```
827
+
828
+ `organizationRole` is `organization_admin`, `organization_operator`, or
829
+ `organization_member`. `groups` is a required array; use `[]` for no memberships.
830
+ A root Group handle or a root/subgroup FQN is accepted and serialized as an FQN
831
+ string. Both `declarePackage` and `parsePackageManifest` require each referenced
832
+ Group to be declared in that same manifest. A matching FQN prefix, a package
833
+ dependency, or a Group's external parent does not make a Group package-owned.
834
+ The declaration contains no credentials or runtime implementation. Deployment
835
+ confirmation and runtime authorization belong to the Host.
836
+
638
837
  ## Organization Settings declarations
639
838
 
640
839
  `declareOrganizationSettings` declares the settings of the Organization that
@@ -658,7 +857,7 @@ export const acmeSettings = declareOrganizationSettings({
658
857
  domains: ["acme.example"],
659
858
  connection: { setupKey: "okta" },
660
859
  provisionMembers: true,
661
- defaultRole: "organization_user"
860
+ defaultRole: "organization_member"
662
861
  }
663
862
  ],
664
863
  applicationConsent: "ask"
@@ -685,8 +884,9 @@ export const acmeSettings = declareOrganizationSettings({
685
884
  Organization SSO declaration of the same package or `{ providerId }` of a
686
885
  pinned dependency; the manifest stores `{ fqn }` or `{ providerId }`.
687
886
  Credentials arrive only through `connection: { setupKey }`.
688
- `provisionMembers` and `defaultRole` (`organization_admin` or
689
- `organization_user`) are required. `applicationConsent` is `ask` or `skip`.
887
+ `provisionMembers` and `defaultRole` (`organization_admin`,
888
+ `organization_operator`, or `organization_member`) are required. Retired roles
889
+ such as `organization_user` and Tenant roles are rejected by manifest admission. `applicationConsent` is `ask` or `skip`.
690
890
  - `locale` holds `defaultLanguage`, `languages` and `timezone`. `governance`
691
891
  holds `accessAuditRetentionMonths` and `maxGroupHierarchyDepth`, positive
692
892
  integers. Domain claims, language codes and the depth range are host checks.
@@ -695,109 +895,133 @@ export const acmeSettings = declareOrganizationSettings({
695
895
  manifest readers reject the same declarations; both use
696
896
  `organizationSettingsViolation`.
697
897
 
698
- ## External application roles and Admitted Classes
898
+ ## External application roles
699
899
 
700
- `declareExternalApplication` accepts two optional access fields: `roles`, the
701
- role tree of the application, and `admits`, the Admitted Classes ceiling. A
702
- third optional field, `applicationConsent`, overrides the Application Consent
900
+ `declareExternalApplication` requires `userRoles` and accepts three optional
901
+ access fields: `serverRoles`, `defaultServerRole` and `groupBindings`. A
902
+ further optional field, `applicationConsent`, overrides the Application Consent
703
903
  rule of the Organization for this application: `inherit` (the default) follows
704
904
  the Organization, `ask` always prompts, `skip` never prompts.
705
905
 
706
- The host stores and checks the roles, the Admitted Classes and the
707
- [Declared Grants](#declared-grants) at install, and shows them to the
708
- Organization admin. It does not yet read them when a user signs in to the
709
- application or calls it.
710
-
711
906
  ```ts
712
- export const partnerPortal = declareExternalApplication({
907
+ export const clinic = declareExternalApplication({
713
908
  definition: {
714
909
  // ...applicationType, audience, redirectUris, scopes, lifecycle
715
- admits: ["internal", "external"],
716
- roles: [
717
- { key: "admin", permissions: ["knowledge:read", "knowledge:manage"] },
718
- { key: "viewer", parent: "admin", permissions: ["knowledge:read"] },
719
- { key: "owner", permissions: ["knowledge:read"], replaces: "superuser" }
910
+ userRoles: [
911
+ {
912
+ key: "doctor",
913
+ platformPermissions: ["knowledge:read", "knowledge:manage"],
914
+ appPermissions: ["appointments:book"],
915
+ users: { create: true },
916
+ assignRoles: ["patient"],
917
+ visibility: "user"
918
+ },
919
+ {
920
+ key: "patient",
921
+ platformPermissions: [],
922
+ visibility: "declared",
923
+ bindings: {
924
+ knowledge: {
925
+ schemas: [
926
+ { fqn: "acme.clinic.schemas.appointment", policy: "own-rows" }
927
+ ]
928
+ },
929
+ agents: ["acme.clinic.agents.booking"]
930
+ }
931
+ },
932
+ {
933
+ key: "anonymous",
934
+ platformPermissions: [],
935
+ visibility: "declared",
936
+ bindings: { agents: ["acme.clinic.agents.booking"] }
937
+ }
938
+ ],
939
+ serverRoles: [
940
+ {
941
+ key: "server",
942
+ platformPermissions: ["knowledge:read"],
943
+ users: { create: true },
944
+ assignRoles: ["patient"],
945
+ bindings: { workflows: "all" }
946
+ }
947
+ ],
948
+ defaultServerRole: "server",
949
+ groupBindings: [
950
+ {
951
+ group: doctorsGroup,
952
+ role: "doctor",
953
+ lifecycle: { deployMode: "upsert", readonly: true }
954
+ }
720
955
  ]
721
956
  },
722
- manifest: { fqn: "acme.portal.application", version: "2.0.0" },
723
- presentation: { displayName: "Partner portal" }
957
+ manifest: { fqn: "acme.clinic.application", version: "1.0.0" },
958
+ presentation: { displayName: "Clinic" }
724
959
  })
725
960
  ```
726
961
 
727
- - A role is an `ExternalApplicationRole`: `key`, `permissions`, an optional
728
- `parent`, and an optional `replaces`.
962
+ - Every role has `key`, `platformPermissions`, and the optional fields
963
+ `parent`, `appPermissions`, `users: { create }`, `assignRoles` and
964
+ `replaces` (`ExternalApplicationRoleBase`).
965
+ - A User Role (`ExternalApplicationUserRole`) has `visibility`. `"user"`
966
+ (User Visibility) shows the resources that CI grants to the user; such a
967
+ role declares no `bindings`. `"declared"` (Declared Visibility) shows the
968
+ optional `bindings` of the role.
969
+ - A Server Role (`ExternalApplicationServerRole`) is the role of a call that
970
+ the application server makes. It has the optional `bindings`. When
971
+ `serverRoles` is not empty, `defaultServerRole` is required and names one of
972
+ them; the host uses it when a server call names no role.
973
+ - `bindings` is an `ExternalApplicationDeclaredBindings`: `knowledge.schemas`
974
+ and `knowledge.domains` list `{ fqn, policy? }` targets; `agents`, `skills`,
975
+ `workflows` and `documents` list FQNs. Each kind is `"all"` or a list; an
976
+ omitted kind binds nothing. The SDK checks the shape only; the host resolves
977
+ the FQNs.
729
978
  - A `key` matches `^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$`, holds at most 64
730
- characters, and is declared one time in the application.
731
- - A permission is a `resource:action` string with one colon and no empty side.
732
- The SDK checks the shape only; the host checks that it knows the permission.
733
- - `parent` is the key of another declared role. A parent role holds every
734
- permission of each of its children, and a role is not its own ancestor. The
735
- helper infers the declared keys, so TypeScript rejects a `parent` that is not
736
- a declared key; the manifest stores plain strings.
979
+ characters, and is declared one time among the User Roles and the Server
980
+ Roles of the application. A role keyed `anonymous` is a User Role with
981
+ Declared Visibility.
982
+ - A Platform Permission is a `resource:action` string. A resource may be
983
+ namespaced, as in `ai:catalog:read`. Each colon-separated segment starts with
984
+ a lowercase letter and contains only lowercase letters, digits or underscores;
985
+ empty segments are invalid. The SDK checks syntax only: `a:b:c` is valid
986
+ syntax, but the backend rejects permissions outside its known catalog.
987
+ App Permissions are strings that the application defines.
988
+ - `parent` is the key of another declared role of the same kind. A parent role
989
+ holds every Platform Permission and App Permission of each of its children,
990
+ and a role is not its own ancestor.
991
+ - `assignRoles` lists keys of User Roles of the same application that a holder
992
+ of the role can assign. `users.create` lets a holder create users.
737
993
  - `replaces` is the key of a role that an earlier release declared and this
738
994
  release removed. It cannot be a key of this release, and two roles cannot
739
995
  replace the same key.
740
- - `admits` is a list of `ExternalApplicationUserClass` values (`internal`,
741
- `external`) with at least one value and no repeated value. The Organization
742
- admin can narrow the list but cannot admit a class outside it. When `admits`
743
- is absent, the application admits internal users only.
996
+ - The helper infers the declared keys, so TypeScript rejects a `parent`, an
997
+ `assignRoles` entry, a `defaultServerRole` or a Group Role Binding `role`
998
+ that is not a declared key of the right kind; the manifest stores plain
999
+ strings.
744
1000
  - `declareExternalApplication` throws a `TypeError` for each violation and
745
1001
  manifest readers reject the same declarations; both use
746
- `externalApplicationViolation`.
747
-
748
- ## Declared Grants
1002
+ `externalApplicationViolation`. A violation message starts with the field
1003
+ path, for example `userRoles[1].parent:`.
749
1004
 
750
- `declareExternalApplication` accepts an optional `grants` list. Each item is a
751
- Declared Grant: one Organization Group holds one role of the application. A
752
- package declares Grants only on its own external application; there is no
753
- separate Grant declaration.
1005
+ ## Group Role Bindings
754
1006
 
755
- ```ts
756
- export const partnerPortal = declareExternalApplication({
757
- definition: {
758
- // ...applicationType, audience, redirectUris, scopes, lifecycle
759
- roles: [
760
- { key: "manager", permissions: ["knowledge:read", "knowledge:manage"] },
761
- { key: "rep", parent: "manager", permissions: ["knowledge:read"] }
762
- ],
763
- grants: [
764
- {
765
- group: salesGroup,
766
- role: "rep",
767
- lifecycle: { deployMode: "init_only", readonly: false }
768
- },
769
- {
770
- group: "acme.directory.groups.sales.managers",
771
- role: "manager",
772
- lifecycle: { deployMode: "upsert", readonly: true }
773
- }
774
- ]
775
- },
776
- manifest: { fqn: "acme.portal.application", version: "2.0.0" },
777
- presentation: { displayName: "Partner portal" }
778
- })
779
- ```
1007
+ `groupBindings` lists Group Role Bindings: the members of one Organization
1008
+ Group hold one User Role of the application. A package declares bindings only
1009
+ on its own external application.
780
1010
 
781
1011
  - `group` is a `DeclarationReference<"organizationGroup">`: the handle that
782
1012
  `declareOrganizationGroup` returns for a root Group of the same package, or
783
1013
  the FQN string of any Group. Use the FQN string for a subgroup and for a
784
1014
  Group that another package declares. TypeScript rejects a handle of another
785
1015
  primitive kind. The manifest stores the FQN string in an
786
- `ExternalApplicationGrant` item.
787
- - The SDK does not check that the Group exists. The host refuses the install
788
- when no Group of the Organization has that FQN and no package of the same
789
- operation declares it.
790
- - `role` is the key of a role that the same declaration declares. The helper
791
- infers the declared keys, so TypeScript rejects another key; the manifest
792
- stores a plain string.
793
- - `lifecycle` is a required `LifecycleOptions` of the Grant, separate from the
794
- lifecycle of the application. An item with no `deployMode` or no `readonly`
795
- is rejected.
1016
+ `ExternalApplicationGroupBinding` item.
1017
+ - The SDK does not check that the Group exists; the host does.
1018
+ - `role` is the key of a User Role of the same declaration.
1019
+ - `coverage` is `"inherited"` (the default when omitted: members of subgroups
1020
+ also hold the role) or `"direct"` (members of the Group only).
1021
+ - `lifecycle` is a required `LifecycleOptions` of the binding, separate from
1022
+ the lifecycle of the application. An item with no `deployMode` or no
1023
+ `readonly` is rejected.
796
1024
  - Two items cannot name the same Group and the same role.
797
- - `declareExternalApplication` throws a `TypeError` for each violation and
798
- manifest readers reject the same declarations. Both use
799
- `externalApplicationViolation` for the Group, the role and the repeated
800
- pair.
801
1025
 
802
1026
  ## Package Variables
803
1027
 
@@ -872,8 +1096,9 @@ export default declarePackage({
872
1096
  - A handle never fits `fqn`, `version`, `kind`, a reference to another
873
1097
  component by FQN (`templateFqn`, `schemaFqn`, ...), `lifecycle` or a schema
874
1098
  projection (`VaryingExcludedKey`); manifest readers reject a marker there
875
- with its path. The access model of an External Application (`admits`,
876
- `grants`, `roles`) and the `provider` of an SSO entry keep their shape.
1099
+ with its path. The access model of an External Application (`userRoles`,
1100
+ `serverRoles`, `defaultServerRole`, `groupBindings`) and the `provider` of
1101
+ an SSO entry keep their shape.
877
1102
  - Manifest readers admit the marker in every other definition value and keep
878
1103
  it; cross-field rules that need the value run after substitution. The host
879
1104
  owns substitution; `isVariableReference(value)` recognizes a marker and
@@ -1249,6 +1474,84 @@ specialized package. The common package deliberately does not export
1249
1474
  `PackageTool`, `PackageRuntimeContext`, `defineCapability`,
1250
1475
  `PackageFieldDefinition`, or `PackageWorkflowField`.
1251
1476
 
1477
+ ### Declared connection instances
1478
+
1479
+ `declareConnectionInstance` provisions an Organization connection from an existing
1480
+ connection template. It uses the same `lifecycle` options as connector instances:
1481
+ `upsert` reconciles the package-owned resource, while `init_only` initializes it.
1482
+ The declaration FQN identifies the connection across deployments. Credentials use
1483
+ existing package variables; keep secret values outside release manifests.
1484
+
1485
+ ```ts
1486
+ import {
1487
+ declareConnectionInstance,
1488
+ declareKnowledgeConnectorInstance,
1489
+ declarePackage,
1490
+ packageVariables
1491
+ } from "@collective-intelligence/extensions-sdk"
1492
+
1493
+ const variables = { notionToken: { type: "secret" } } as const
1494
+ const vars = packageVariables(variables)
1495
+ const templateFqn =
1496
+ "builtin.integrations.notion.connections.internal-integration-token"
1497
+ const connectionInstanceFqn = "acme.connections.notion"
1498
+ const lifecycle = { deployMode: "upsert", readonly: false } as const
1499
+
1500
+ const notionConnection = declareConnectionInstance({
1501
+ manifest: { fqn: connectionInstanceFqn, version: "1.0.0" },
1502
+ presentation: { displayName: "Company Notion" },
1503
+ definition: {
1504
+ templateFqn,
1505
+ lifecycle,
1506
+ credentials: { integrationToken: vars.notionToken }
1507
+ }
1508
+ })
1509
+ const notionConnector = declareKnowledgeConnectorInstance({
1510
+ manifest: { fqn: "acme.connectors.notion", version: "1.0.0" },
1511
+ presentation: { displayName: "Company Notion content" },
1512
+ definition: {
1513
+ templateFqn: "builtin.integrations.notion.connectors.api",
1514
+ lifecycle,
1515
+ connections: { notion: { connectionInstanceFqn } }
1516
+ }
1517
+ })
1518
+ export default declarePackage({
1519
+ manifest: {
1520
+ fqn: "acme",
1521
+ name: "Acme",
1522
+ version: "1.0.0",
1523
+ dependencies: [{ fqn: "builtin.integrations.notion" }]
1524
+ },
1525
+ variables,
1526
+ components: [notionConnection, notionConnector]
1527
+ })
1528
+ ```
1529
+
1530
+ Use the connector template FQN and slot declared by your installed package.
1531
+ A Dataset connector selects the same reference in `definition.connection`.
1532
+ Connector selections accept exactly one of `{ setupKey }` and
1533
+ `{ connectionInstanceFqn }`. Tool and connector template `connectionRefs` can
1534
+ also set `connectionInstanceFqn` beside their required `connectionTemplateFqn`,
1535
+ `slot`, and `label`. The selected instance must use that exact template.
1536
+ FQNs and lifecycle remain static; they cannot be package-variable references.
1537
+
1538
+ Supply the secret through the existing deploy inputs:
1539
+
1540
+ ```json
1541
+ {
1542
+ "variables": {
1543
+ "notionToken": { "link": "NOTION_INTEGRATION_TOKEN" }
1544
+ }
1545
+ }
1546
+ ```
1547
+
1548
+ Declared connection references do not require an additional manual connection
1549
+ setup slot. A `secret` variable has no default. A missing linked Organization
1550
+ secret is created pending; fill its value through Organization variables before
1551
+ using the connection. Pending credentials stop provider calls. The Host validates
1552
+ template eligibility, credential fields, and secret references before provisioning.
1553
+ References may target this package or its declared dependencies.
1554
+
1252
1555
  ### Connections and connectors
1253
1556
 
1254
1557
  `PackageConnection` implementations own advertised `test` and `discover`
@@ -1523,7 +1826,13 @@ then read it with `parseStoredExtensionReleaseManifest`, which maps each retired
1523
1826
  kind (for example `tool_collection`) to its current spelling. The same read maps
1524
1827
  the Organization Team names of earlier releases to Organization Group names: the
1525
1828
  Agent audience key `organizationTeams`, and the managed projection names such as
1526
- `directory_team`.
1829
+ `directory_team`. Historical Entity Relation Field cardinalities map `one` to
1830
+ `many_to_one` and `many` to `many_to_many`, preserving unbounded reverse sharing.
1831
+ The stored reader removes a valid redundant `maxItems` from legacy scalar `one`;
1832
+ list limits and all other relation settings remain intact. Malformed values still
1833
+ fail declaration validation. This conversion creates a read projection: retained
1834
+ release JSON, archive bytes and their provenance remain unchanged and must be
1835
+ verified before conversion.
1527
1836
  `withCurrentPrimitiveKinds` applies the same mapping to stored JSON without
1528
1837
  parsing it. `parseExtensionReleaseManifest` and `parsePackageManifest` accept
1529
1838
  only the current spelling.
@@ -2015,3 +2324,34 @@ Add these settings to the existing schema declaration's `definition` object:
2015
2324
  }
2016
2325
  }
2017
2326
  ```
2327
+
2328
+ ### Per-source run data access
2329
+
2330
+ `declareAgent`, `declareSkill`, and `declareWorkflow` accept optional
2331
+ `definition.dataAccess`. Its optional `knowledge`, `datasets`, and `documents`
2332
+ entries select `"user"` or the declaration's own kind (`"agent"`, `"skill"`, or
2333
+ `"workflow"`). The exported `DataAccess<Own>` type describes this portable
2334
+ contract. For example, an Agent can declare:
2335
+
2336
+ ```ts
2337
+ import type { DataAccess } from "@collective-intelligence/extensions-sdk"
2338
+
2339
+ const dataAccess = {
2340
+ knowledge: "user",
2341
+ documents: "agent"
2342
+ } satisfies DataAccess<"agent">
2343
+ ```
2344
+
2345
+ An omitted object or entry means the runtime's own kind. `user` selects the
2346
+ visibility of the identity the run acts for. The own-kind setting selects its
2347
+ configured resources, still limited by their own bindings. Each source is
2348
+ independent; the setting grants no additional tool or resource bindings.
2349
+
2350
+ Workflow declarations copy this setting into `definition.definition.dataAccess`
2351
+ (the portable authored graph) and retain it at `definition.dataAccess`. A
2352
+ setting supplied only on the graph is also accepted. When both locations are
2353
+ supplied, they must agree for every source after omitted entries default to
2354
+ `workflow`; conflicts are rejected. Canonical package manifests preserve these
2355
+ settings and reject unknown sources or another runtime's kind. These SDK checks
2356
+ validate declarations; the Host implements runtime authorization and per-step
2357
+ rechecks.
@@ -3,6 +3,7 @@ import type { PackageSchemaProjection } from "../schema/projection.js";
3
3
  import type { PackageCodecSource } from "../schema/source.js";
4
4
  import type { ComponentManifest, ComponentPresentation, DeclarationReference, DeclaredComponent } from "./authoring-core.js";
5
5
  import type { PackagePrimitiveBase } from "./base.js";
6
+ import type { DataAccess } from "./data-access.js";
6
7
  import type { LifecycleOptions } from "./lifecycle.js";
7
8
  /** Idle activation sources. Each stays off unless declared `true`. */
8
9
  export type AgentActivityPolicy = Readonly<{
@@ -95,6 +96,7 @@ export type AgentModelTier = (typeof agentModelTiers)[number];
95
96
  * `skills` and own `tools` are FQN references resolved at install.
96
97
  */
97
98
  export type AgentDeclaration = PackagePrimitiveBase<"agent"> & Readonly<{
99
+ dataAccess?: DataAccess<"agent">;
98
100
  activity?: AgentActivityPolicy;
99
101
  audience?: AgentAudienceDeclaration;
100
102
  behavioralBoundaries: readonly string[];
@@ -119,6 +121,7 @@ export type AgentDeclaration = PackagePrimitiveBase<"agent"> & Readonly<{
119
121
  }>;
120
122
  /** Portable governed Skill held by Agents and loaded on demand. */
121
123
  export type SkillDeclaration = PackagePrimitiveBase<"skill"> & Readonly<{
124
+ dataAccess?: DataAccess<"skill">;
122
125
  instructions: string;
123
126
  lifecycle: LifecycleOptions;
124
127
  tools: DeclaredToolBindings;
@@ -1,6 +1,6 @@
1
1
  import type { VisibilityCondition } from "../schema/forms.js";
2
2
  export type BindingScope = "organization" | "tenant";
3
- export type PackagePrimitiveKind = "agent" | "knowledgeEntityAdapter" | "connection" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgeRelationSchema" | "knowledgePolicy" | "notificationChannel" | "organizationGroup" | "organizationSettings" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "knowledgeRelationAdapter" | "skill" | "skillTemplate" | "studioApp" | "studioAppTemplate" | "studioComponent" | "tool" | "toolCollection" | "toolSettingsOptions" | "workflow" | "workflowField" | "workflowFieldCollection" | "workflowNode" | "workflowNodeCollection" | "workflowTemplate";
3
+ export type PackagePrimitiveKind = "agent" | "knowledgeEntityAdapter" | "connection" | "connectionInstance" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgeRelationSchema" | "knowledgePolicy" | "notificationChannel" | "organizationGroup" | "organizationSettings" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "knowledgeRelationAdapter" | "servicePrincipal" | "skill" | "skillTemplate" | "studioApp" | "studioAppTemplate" | "studioComponent" | "tool" | "toolCollection" | "toolSettingsOptions" | "workflow" | "workflowField" | "workflowFieldCollection" | "workflowNode" | "workflowNodeCollection" | "workflowTemplate";
4
4
  export type PackagePrimitiveBase<Kind extends PackagePrimitiveKind> = Readonly<{
5
5
  description?: string;
6
6
  displayName: string;
@@ -17,6 +17,7 @@ export type ConnectionReference = Readonly<{
17
17
  * `PackageRuntimeContext.connectionCatalogIds[slot]`.
18
18
  */
19
19
  catalogCollection?: string;
20
+ connectionInstanceFqn?: string;
20
21
  connectionTemplateFqn: string;
21
22
  label: string;
22
23
  required?: boolean;
@@ -0,0 +1,9 @@
1
+ import type { JsonValue } from "../foundation/json.js";
2
+ import type { PackagePrimitiveBase } from "./base.js";
3
+ import type { LifecycleOptions } from "./lifecycle.js";
4
+ /** An organization connection provisioned with the package lifecycle. */
5
+ export type ConnectionInstanceDeclaration = PackagePrimitiveBase<"connectionInstance"> & Readonly<{
6
+ templateFqn: string;
7
+ lifecycle: LifecycleOptions;
8
+ credentials: Readonly<Record<string, JsonValue>>;
9
+ }>;