@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ebaebc4

package/authoring/gap-report/parse.d.mts

@@ -2,8 +2,8 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>
  * >} _GapReportReceiptDriftLock
  */
 /**
@@ -25,23 +25,23 @@ export function parseGapReportHandler(input: unknown, label?: string): GapReport
  * @returns {GapReportHandlerReceipt | null}
  */
 export function parseGapReportReceipt(input: unknown): GapReportHandlerReceipt | null;
-export type _GapReportReceiptDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>>;
-export type GapReportHandler = import("./type").GapReportHandler;
-export type GapReportHandlerReceipt = import("./type").GapReportHandlerReceipt;
+export type _GapReportReceiptDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>>;
+export type GapReportHandler = import("./type.js").GapReportHandler;
+export type GapReportHandlerReceipt = import("./type.js").GapReportHandlerReceipt;
 /**
  * Compile-time drift-lock: the sealed schema must infer EXACTLY the public
  * {@link GapReportHandler} type. If they drift, `MutuallyAssignable` becomes
  * `false` and `Expect<false>` fails `tsconfig.authoring-contract.json`.
  */
-export type _GapReportHandlerDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>>;
+export type _GapReportHandlerDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>>;
 import { z } from 'zod';
 /**
  * Compile-time drift-lock: the sealed schema must infer EXACTLY the public
  * {@link GapReportHandler} type. If they drift, `MutuallyAssignable` becomes
  * `false` and `Expect<false>` fails `tsconfig.authoring-contract.json`.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>
  * >} _GapReportHandlerDriftLock
  */
 declare const receiptSchema: z.ZodObject<{
@@ -55,9 +55,9 @@ declare const receiptSchema: z.ZodObject<{
 }, z.core.$strict>;
 declare const handlerSchema: z.ZodObject<{
     audience: z.ZodEnum<{
-        internal: "internal";
         public: "public";
+        internal: "internal";
     }>;
-    handle: z.ZodType<(report: import("./type").GapReport, context: import("./type").GapReportHandlerContext) => import("./type").GapReportHandlerReceipt | Promise<import("./type").GapReportHandlerReceipt>, any, z.core.$ZodTypeInternals<(report: import("./type").GapReport, context: import("./type").GapReportHandlerContext) => import("./type").GapReportHandlerReceipt | Promise<import("./type").GapReportHandlerReceipt>, any>>;
+    handle: z.ZodType<(report: import("./type.js").GapReport, context: import("./type.js").GapReportHandlerContext) => import("./type.js").GapReportHandlerReceipt | Promise<import("./type.js").GapReportHandlerReceipt>, any, z.core.$ZodTypeInternals<(report: import("./type.js").GapReport, context: import("./type.js").GapReportHandlerContext) => import("./type.js").GapReportHandlerReceipt | Promise<import("./type.js").GapReportHandlerReceipt>, any>>;
 }, z.core.$strict>;
 export {};

package/authoring/gap-report/parse.mjs

@@ -13,8 +13,8 @@
 import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./type').GapReportHandler} GapReportHandler */
-/** @typedef {import('./type').GapReportHandlerReceipt} GapReportHandlerReceipt */
+/** @typedef {import('./type.js').GapReportHandler} GapReportHandler */
+/** @typedef {import('./type.js').GapReportHandlerReceipt} GapReportHandlerReceipt */
 
 // Typed z.custom so z.infer reproduces the real function type, matching the
 // pattern used by the debug handler and post-codemod hook parsers.
@@ -36,8 +36,8 @@ const handlerSchema = z
  * {@link GapReportHandler} type. If they drift, `MutuallyAssignable` becomes
  * `false` and `Expect<false>` fails `tsconfig.authoring-contract.json`.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof handlerSchema>, GapReportHandler>
  * >} _GapReportHandlerDriftLock
  */
 
@@ -50,8 +50,8 @@ const receiptSchema = z
   .strict();
 
 /**
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof receiptSchema>, GapReportHandlerReceipt>
  * >} _GapReportReceiptDriftLock
  */
 

package/authoring/gap-report/type.ts

@@ -14,7 +14,7 @@
  * gap-report handlers.
  */
 
-import type {DebugInvocationSource} from '../debug/type';
+import type {DebugInvocationSource} from '../debug/type.js';
 
 /** Supported gap-report categories. */
 export type GapReportCategory =

package/authoring/identity/identity.doc.d.mts

@@ -0,0 +1,9 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for provider, artifact, and immutable instance identity.
+ * @position packages/cli/authoring/identity — identity documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

package/authoring/identity/identity.doc.mjs

@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SchemaDoc for provider, artifact, and immutable instance identity.
+ * @position packages/cli/authoring/identity — identity documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc = {
+  type: 'schema',
+  name: 'provider-identity',
+  displayName: 'Provider and artifact identity',
+  namespace: 'authoring',
+  description:
+    'Separates stable provider/artifact identity from package instances and runtime lifecycle state. providerId is in use today: an integration manifest may declare it, and Doctor and every command report two packages that claim one. The artifact, doc, instance, and compiler-input identities are defined for the docs graph, which is not built yet, and no command reads them.',
+  appliesTo:
+    'Integration manifests and provider conflicts today; the docs graph once it ships',
+  fields: [
+    {
+      name: 'ProviderId',
+      type: 'string',
+      description:
+        'Canonical logical provider ID. It defaults to the lowercase npm package name; Core uses the same model without publishing an integration manifest.',
+      required: true,
+    },
+    {
+      name: 'ArtifactId',
+      type: 'string',
+      description:
+        'Versioned serialization of provider ID, contribution kind, and stable artifact name. Every segment uses RFC 3986 escaping.',
+      required: true,
+    },
+    {
+      name: 'DocId',
+      type: 'ArtifactId',
+      description:
+        'Artifact ID restricted to one authored doc kind. Navigation changes do not change it.',
+      required: true,
+    },
+    {
+      name: 'ProviderInstance',
+      type: '{ id; providerId; packageName; packageVersion; sourceDigest }',
+      description:
+        'One immutable package version and source/content digest. Installed, configured, loaded, selected, and healthy state is a separate runtime overlay.',
+      required: true,
+    },
+    {
+      name: 'AuthoredDocEntry',
+      type: '{ id; provider; kind; stableName; source; authored }',
+      description:
+        'Normalized compiler input. Discovery supplies stableName independently from the authored display name, source paths remain package-relative, and provider provenance plus the authored snapshot are immutable.',
+      required: true,
+    },
+  ],
+  notes: [
+    {
+      type: 'prose',
+      text: 'Provider package renames require an explicit mapping: a ProviderInstance may retain its stable providerId while packageName changes. Silent identity changes are not inferred.',
+    },
+  ],
+};

package/authoring/identity/type.ts

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Stable provider, artifact, and authored-doc entry contracts.
+ *
+ * Logical IDs exclude installed/configured/loaded/healthy state. A concrete
+ * provider instance adds package version and a content digest, while an
+ * artifact ID stays stable across those instances.
+ */
+
+import type {AuthoredDocKind} from '../doctypes/base/type.js';
+import type {CommandDoc} from '../doctypes/command/type.js';
+import type {ComponentDoc} from '../doctypes/component/type.js';
+import type {EnumDoc} from '../doctypes/enum/type.js';
+import type {FunctionDoc} from '../doctypes/function/type.js';
+import type {HookDoc} from '../doctypes/hook/type.js';
+import type {NamespaceDoc} from '../doctypes/namespace/type.js';
+import type {ReferenceDoc} from '../doctypes/reference/type.js';
+import type {SchemaDoc} from '../doctypes/schema/type.js';
+import type {TemplateDoc} from '../doctypes/template/type.js';
+
+declare const providerIdBrand: unique symbol;
+declare const artifactIdBrand: unique symbol;
+declare const docIdBrand: unique symbol;
+declare const providerInstanceIdBrand: unique symbol;
+declare const contentDigestBrand: unique symbol;
+
+/** Canonical provider identity. It defaults to the normalized npm package name. */
+export type ProviderId = string & {readonly [providerIdBrand]: true};
+
+/** Stable provider + contribution kind + artifact-name identity. */
+export type ArtifactId = string & {readonly [artifactIdBrand]: true};
+
+/** ArtifactId narrowed to an authored documentation kind. */
+export type DocId = ArtifactId & {readonly [docIdBrand]: true};
+
+/** Immutable provider version + source/content digest identity. */
+export type ProviderInstanceId = string & {
+  readonly [providerInstanceIdBrand]: true;
+};
+
+/** Lowercase `sha256:<64 hex characters>` digest. */
+export type ContentDigest = string & {readonly [contentDigestBrand]: true};
+
+/** Every stable artifact kind owned by a provider. */
+export type ContributionKind =
+  AuthoredDocKind | 'theme' | 'codemod' | 'agent-doc';
+
+/** Stable logical identity for one provider-owned artifact. */
+export interface ArtifactIdentity {
+  readonly id: ArtifactId;
+  readonly providerId: ProviderId;
+  readonly kind: ContributionKind;
+  readonly name: string;
+}
+
+/** One immutable package instance. Runtime lifecycle state does not belong here. */
+export interface ProviderInstance {
+  readonly id: ProviderInstanceId;
+  readonly providerId: ProviderId;
+  readonly packageName: string;
+  readonly packageVersion: string;
+  readonly sourceDigest: ContentDigest;
+}
+
+/** Every authored value accepted by the documentation compiler boundary. */
+export type AuthoredDoc =
+  | ComponentDoc
+  | HookDoc
+  | FunctionDoc
+  | ReferenceDoc
+  | TemplateDoc
+  | SchemaDoc
+  | CommandDoc
+  | EnumDoc
+  | NamespaceDoc;
+
+/** Provenance attached by discovery before compilation. */
+export interface AuthoredDocSource {
+  /** Provider-local logical discovery group. */
+  readonly group: string;
+  /** Package-relative source path; excluded from compiled renderer data. */
+  readonly path: string;
+  /** Digest of the authored source bytes. */
+  readonly digest: ContentDigest;
+}
+
+/** Authored kind that corresponds to one public document type. */
+export type AuthoredDocKindOf<TDoc extends AuthoredDoc> =
+  TDoc extends ComponentDoc
+    ? 'component'
+    : TDoc extends HookDoc | FunctionDoc
+      ? 'function'
+      : TDoc extends ReferenceDoc
+        ? 'generic'
+        : TDoc extends TemplateDoc
+          ? TDoc['type']
+          : TDoc extends SchemaDoc
+            ? 'schema'
+            : TDoc extends CommandDoc
+              ? 'command'
+              : TDoc extends EnumDoc
+                ? 'enum'
+                : TDoc extends NamespaceDoc
+                  ? 'namespace'
+                  : never;
+
+type DeepReadonly<Value> = Value extends (...args: never[]) => unknown
+  ? Value
+  : Value extends readonly (infer Item)[]
+    ? readonly DeepReadonly<Item>[]
+    : Value extends object
+      ? {readonly [Key in keyof Value]: DeepReadonly<Value[Key]>}
+      : Value;
+
+/** Immutable authored-data snapshot stored in a compiler entry. */
+export type AuthoredDocSnapshot<TDoc extends AuthoredDoc = AuthoredDoc> =
+  DeepReadonly<TDoc>;
+
+/**
+ * One normalized compiler input. Stable identity is provider + authored kind +
+ * stable name; provider version and source bytes remain explicit provenance.
+ */
+export interface AuthoredDocEntry<TDoc extends AuthoredDoc = AuthoredDoc> {
+  readonly id: DocId;
+  readonly provider: ProviderInstance;
+  readonly kind: AuthoredDocKindOf<TDoc>;
+  /** Stable provider-local key used in the DocId; it need not equal a display name. */
+  readonly stableName: string;
+  readonly source: AuthoredDocSource;
+  readonly authored: AuthoredDocSnapshot<TDoc>;
+}

package/authoring/index.d.mts

@@ -14,5 +14,6 @@ export { parseTemplate } from "./doctypes/template/parse.mjs";
 export { parseSchema } from "./doctypes/schema/parse.mjs";
 export { parseCommand } from "./doctypes/command/parse.mjs";
 export { parseEnum } from "./doctypes/enum/parse.mjs";
+export { parseNamespace } from "./doctypes/namespace/parse.mjs";
 export { parseLegacyDoc } from "./doctypes/legacy.mjs";
 export { parseGapReportHandler, parseGapReportReceipt } from "./gap-report/parse.mjs";

package/authoring/index.d.ts

@@ -23,17 +23,18 @@
 // ═══════════════════════════════════════════════════════════════════════
 // AUTHOR THESE — each is the default export of one authored file.
 // ═══════════════════════════════════════════════════════════════════════
-export type {ComponentDoc} from './doctypes/types'; //   Button.doc.{ts,mjs}
-export type {HookDoc} from './doctypes/types'; //         useToast.doc.{ts,mjs}
-export type {FunctionDoc} from './doctypes/types'; //     search.doc.mjs (hook | api)
-export type {ReferenceDoc} from './doctypes/types'; //    theming.doc.{ts,mjs}
-export type {TemplateDoc} from './doctypes/types'; //     Foo.template.{ts,mjs}
-export type {SchemaDoc} from './doctypes/types'; //       config.doc.mjs (object shape)
-export type {CommandDoc} from './doctypes/types'; //      search.doc.mjs (CLI command)
-export type {EnumDoc} from './doctypes/types'; //         error-codes.doc.mjs (vocabulary)
-export type {AstryxConfig} from './config/type'; //       astryx.config.{ts,mjs}
-export type {DebugEvent} from './debug/type'; //          one recorded CLI run
-export type {AstryxIntegration} from './integration/type'; // astryx.integration.{ts,mjs}
+export type {ComponentDoc} from './doctypes/types.js'; //   Button.doc.{ts,mjs}
+export type {HookDoc} from './doctypes/types.js'; //         useToast.doc.{ts,mjs}
+export type {FunctionDoc} from './doctypes/types.js'; //     search.doc.mjs (hook | api)
+export type {ReferenceDoc} from './doctypes/types.js'; //    theming.doc.{ts,mjs}
+export type {TemplateDoc} from './doctypes/types.js'; //     Foo.template.{ts,mjs}
+export type {SchemaDoc} from './doctypes/types.js'; //       config.doc.mjs (object shape)
+export type {CommandDoc} from './doctypes/types.js'; //      search.doc.mjs (CLI command)
+export type {EnumDoc} from './doctypes/types.js'; //         error-codes.doc.mjs (vocabulary)
+export type {NamespaceDoc} from './doctypes/types.js'; //    cli.doc.mjs (hierarchy)
+export type {AstryxConfig} from './config/type.js'; //       astryx.config.{ts,mjs}
+export type {DebugEvent} from './debug/type.js'; //          one recorded CLI run
+export type {AstryxIntegration} from './integration/type.js'; // astryx.integration.{ts,mjs}
 export type {
   GapReportHandler,
   GapReportHandlerContext,
@@ -41,8 +42,8 @@ export type {
   GapReportCategory,
   GapReportTarget,
   GapReportHandlerReceipt,
-} from './gap-report/type'; // gap-report handler contract
-export type {AstryxCodemod, AstryxConfigCodemod} from './codemod/type'; // codemods/*
+} from './gap-report/type.js'; // gap-report handler contract
+export type {AstryxCodemod, AstryxConfigCodemod} from './codemod/type.js'; // codemods/*
 
 // ═══════════════════════════════════════════════════════════════════════
 // PARSERS — the CLI's load boundary (types come from each parser's JSDoc).
@@ -56,6 +57,7 @@ export {parseTemplate} from './doctypes/template/parse.mjs';
 export {parseSchema} from './doctypes/schema/parse.mjs';
 export {parseCommand} from './doctypes/command/parse.mjs';
 export {parseEnum} from './doctypes/enum/parse.mjs';
+export {parseNamespace} from './doctypes/namespace/parse.mjs';
 export {parseLegacyDoc} from './doctypes/legacy.mjs';
 export {parseConfig} from './config/parse.mjs';
 export {parseIntegration} from './integration/parse.mjs';
@@ -72,6 +74,26 @@ export {parseDebugEvent} from './debug/parse.mjs';
 // need them to author. Names carry the doc kind they belong to.
 // ═══════════════════════════════════════════════════════════════════════
 export type {
+  ProviderId,
+  ArtifactId,
+  DocId,
+  ProviderInstanceId,
+  ContentDigest,
+  ContributionKind,
+  ArtifactIdentity,
+  ProviderInstance,
+  AuthoredDoc,
+  AuthoredDocKindOf,
+  AuthoredDocSnapshot,
+  AuthoredDocSource,
+  AuthoredDocEntry,
+} from './identity/type.js';
+export type {
+  // shared graph
+  AuthoredDocKind,
+  DocAudience,
+  DocPlacement,
+  AuthoredDocGraphFields,
   // component
   SingleComponentDoc,
   MultiComponentDoc,
@@ -109,6 +131,16 @@ export type {
   ReferenceContentBlock,
   ReferenceTokenPreviewType,
   ReferenceTranslationDoc,
+  WorkflowStep,
+  WorkflowDocBlock,
+  CollectionDocBlock,
+  ReferenceDocBlock,
+  // namespace
+  NamespaceProviderScope,
+  NamespaceSlotAcceptance,
+  NamespaceSlot,
+  NamespaceAdoptionSource,
+  NamespaceAdoptionRule,
   // template
   TemplateCategory,
   // schema
@@ -119,8 +151,8 @@ export type {
   CommandExampleDoc,
   // enum
   EnumMemberDoc,
-} from './doctypes/types';
-export type {PostCodemodHook, DebugConfig} from './config/type';
+} from './doctypes/types.js';
+export type {PostCodemodHook, DebugConfig} from './config/type.js';
 export type {
   // debug
   DebugSchemaVersion,
@@ -133,11 +165,11 @@ export type {
   DebugEventEnv,
   DebugEventProject,
   DebugEventHandler,
-} from './debug/type';
+} from './debug/type.js';
 export type {
   AstryxCodemodDef,
   AstryxConfigCodemodDef,
   AstryxCodemodFile,
   AstryxCodemodApi,
   AstryxCodemodTransform,
-} from './codemod/type';
+} from './codemod/type.js';

package/authoring/index.mjs

@@ -31,4 +31,5 @@ export {parseTemplate} from './doctypes/template/parse.mjs';
 export {parseSchema} from './doctypes/schema/parse.mjs';
 export {parseCommand} from './doctypes/command/parse.mjs';
 export {parseEnum} from './doctypes/enum/parse.mjs';
+export {parseNamespace} from './doctypes/namespace/parse.mjs';
 export {parseLegacyDoc} from './doctypes/legacy.mjs';

package/authoring/integration/integration.doc.mjs

@@ -14,11 +14,18 @@ export const doc = {
   namespace: 'cli',
   description:
     'The astryx.integration.* manifest that sits beside an integration ' +
-    "package's package.json. Points the CLI at the package's components, " +
-    'templates, codemods, doc topics, source themes, and managed agent guidance, ' +
-    'and where to file issues. Every field is optional.',
+    "package's package.json. It can preserve a stable provider identity across a package rename, " +
+    "and points the CLI at the package's components, templates, codemods, doc topics, " +
+    'source themes, managed agent guidance, and issue tracker. Every field is optional.',
   appliesTo: 'astryx.integration.{ts,mjs,js}',
   fields: [
+    {
+      name: 'providerId',
+      type: 'string',
+      description:
+        'Stable logical provider ID. Omit to use package.json#name; set it to the prior package name only when an explicit rename must preserve artifact IDs. If two packages claim the same ID, the package being authored is used, otherwise the first-loaded one, and the CLI warns about the other.',
+      example: "'@acme/widgets'",
+    },
     {
       name: 'components',
       type: 'string',
@@ -87,9 +94,9 @@ export const doc = {
     {
       type: 'prose',
       text:
-        "Identity, the integration's name and version, comes from the " +
-        "package's package.json, not from this manifest. The manifest only " +
-        'declares where the CLI finds each kind of artifact.',
+        'Provider identity defaults to package.json#name. During an explicit ' +
+        'package rename, set `providerId` to the prior canonical package name so ' +
+        'existing artifact IDs remain stable. Package version always comes from package.json.',
     },
     {
       type: 'prose',

package/authoring/integration/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('./type').AstryxIntegration} AstryxIntegration */
+/** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 /**
  * Validate an unknown value as an Astryx integration manifest, or throw.
  *
@@ -14,4 +14,4 @@
  * @returns {AstryxIntegration}
  */
 export function parseIntegration(input: unknown, label?: string): AstryxIntegration;
-export type AstryxIntegration = import("./type").AstryxIntegration;
+export type AstryxIntegration = import("./type.js").AstryxIntegration;

package/authoring/integration/parse.mjs

@@ -14,7 +14,7 @@
 import {formatZodError} from '../_shared/errors.mjs';
 import {integrationSchema} from './schema.mjs';
 
-/** @typedef {import('./type').AstryxIntegration} AstryxIntegration */
+/** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 
 /**
  * Validate an unknown value as an Astryx integration manifest, or throw.

package/authoring/integration/parse.test.mjs

@@ -28,6 +28,9 @@ describe('parseIntegration (load boundary)', () => {
       components: './src',
     });
     expect(parseIntegration({docs: './docs'})).toEqual({docs: './docs'});
+    expect(parseIntegration({providerId: '@acme/legacy-widgets'})).toEqual({
+      providerId: '@acme/legacy-widgets',
+    });
     expect(parseIntegration({themes: './themes'})).toEqual({
       themes: './themes',
     });
@@ -66,7 +69,9 @@ describe('parseIntegration (load boundary)', () => {
           ? 'https://example.com/issues'
           : key === 'agentDocs'
             ? {}
-            : './x',
+            : key === 'providerId'
+              ? '@acme/widgets'
+              : './x',
       ]),
     );
     expect(unknownIntegrationKeys(everyKnownKey)).toEqual([]);
@@ -82,6 +87,10 @@ describe('parseIntegration (load boundary)', () => {
     expect(reason({issuesUrl: 'nope'})).toContain('issuesUrl');
   });
 
+  it('rejects a noncanonical providerId', () => {
+    expect(reason({providerId: 'Acme Widgets'})).toContain('providerId');
+  });
+
   it('accepts an optional append array as manifest data', () => {
     expect(
       parseIntegration({

package/authoring/integration/schema.d.mts

@@ -32,6 +32,7 @@ export const agentDocsSchema: z.ZodObject<{
     append: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>;
 export const integrationBaseSchema: z.ZodObject<{
+    providerId: z.ZodOptional<z.ZodString>;
     components: z.ZodOptional<z.ZodString>;
     templates: z.ZodOptional<z.ZodString>;
     codemods: z.ZodOptional<z.ZodString>;
@@ -40,6 +41,7 @@ export const integrationBaseSchema: z.ZodObject<{
     issuesUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export const integrationSchema: z.ZodObject<{
+    providerId: z.ZodOptional<z.ZodString>;
     components: z.ZodOptional<z.ZodString>;
     templates: z.ZodOptional<z.ZodString>;
     codemods: z.ZodOptional<z.ZodString>;
@@ -53,8 +55,8 @@ export const integrationSchema: z.ZodObject<{
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
  * >} _IntegrationDriftLock
  */
 /**
@@ -67,9 +69,9 @@ export const integrationSchema: z.ZodObject<{
  * @type {string[]}
  */
 export const KNOWN_INTEGRATION_KEYS: string[];
-export type AstryxIntegration = import("./type").AstryxIntegration;
+export type AstryxIntegration = import("./type.js").AstryxIntegration;
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  */
-export type _IntegrationDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").Equal<z.infer<typeof integrationSchema>, AstryxIntegration>>;
+export type _IntegrationDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof integrationSchema>, AstryxIntegration>>;
 import { z } from 'zod';

package/authoring/integration/schema.mjs

@@ -16,11 +16,13 @@
 import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./type').AstryxIntegration} AstryxIntegration */
+/** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 
 const MAX_AGENT_DOC_LINES = 8;
 const MAX_AGENT_DOC_LINE_CODE_POINTS = 240;
 const MANAGED_MARKER_TEXT = /(?:ASTRYX|XDS):(START|END)/u;
+const PROVIDER_ID_RE =
+  /^(?:@[a-z0-9][a-z0-9._~!*'()-]*\/)?[a-z0-9][a-z0-9._~!*'()-]*$/u;
 
 /**
  * @param {string} value
@@ -66,6 +68,10 @@ export const agentDocsSchema = z.object({
 });
 
 export const integrationBaseSchema = z.object({
+  providerId: z
+    .string()
+    .regex(PROVIDER_ID_RE, 'providerId must be a canonical npm package name')
+    .optional(),
   components: z.string().optional(),
   templates: z.string().optional(),
   codemods: z.string().optional(),
@@ -115,8 +121,8 @@ export function parseAgentDocsField(input, label) {
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
  * >} _IntegrationDriftLock
  */