deepline 0.3.88 → 0.3.90

package/dist/release.d.mts

@@ -0,0 +1,255 @@
+/// <reference path="./text-imports.d.ts" />
+/**
+ * Single source of truth for SDK release metadata.
+ *
+ * Ordinary SDK PRs do NOT bump `version` here. Patch version selection
+ * happens at publish time: on push to main, `.github/workflows/sdk-release.yml`
+ * (via `scripts/sdk-release-autobump.ts`) compares the built package against
+ * the latest published npm tarball and, when the content changed, stamps the
+ * next unpublished patch into `version` in the CI workspace only and
+ * publishes it in the same run. That patch stamp is not
+ * committed back to main; production endpoints read npm metadata when they
+ * need the newest patch-level SDK/CLI version.
+ *
+ * Edit THIS file by hand only for deliberate release decisions:
+ *   - minor/major version bumps (set `version`),
+ *   - API-major cutovers (set `contracts.api.currentMajor`; leave `version` to the
+ *     publish-time patch selector),
+ *   - support-window moves (`minimumSupported` / `deprecatedBelow`).
+ * The automation never touches API compatibility policy, `minimumSupported`, or
+ * `deprecatedBelow`.
+ *
+ * Everything else derives from these values:
+ *
+ *   - `packages/sdk/src/version.ts` re-exports `SDK_VERSION` and `SDK_API_CONTRACT`.
+ *   - `apps/deepline-api/src/lib/sdk/release-policy.ts` re-exports `SDK_RELEASE_POLICY`.
+ *   - `packages/sdk/package.json` `version` is stamped from `SDK_RELEASE.version` by
+ *     `scripts/sync-sdk-package-version.ts`, which runs as part of
+ *     `bun run sdk:build`.
+ *   - `contracts/sdk-api.manifest.json` is regenerated at build time from
+ *     `apps/deepline-api/src/lib/sdk/api-routes.ts` and the apiContract here; the matching
+ *     `contracts/sdk-api.manifest.hash` is an ignored local/CI audit artifact.
+ *
+ * Any drift between release source and derived release locations is a
+ * `check:sdk-release-readiness` failure with a one-shot fix command; SDK/API
+ * compatibility policy is enforced by `bun run sdk:api-contract:check`.
+ */
+type SdkReleaseChannel = 'latest' | 'next' | 'beta';
+/**
+ * The named public protocols. These are intentionally independent:
+ *
+ * - `api` is the HTTP SDK/CLI protocol. It is additive within a major.
+ * - `playArtifact` is the immutable client-bundled Play payload ABI.
+ * - `release` controls promotion/publishing; it is not a client protocol.
+ *
+ * Do not use an SDK package version or a date string as an artifact ABI.
+ */
+type DeeplineContractPolicy = {
+    api: {
+        name: 'sdk-http-api';
+        currentMajor: number;
+        supportedMajors: readonly number[];
+        /** Transitional value for installed SDKs that only send the old header. */
+        legacyWireIds: readonly string[];
+    };
+    playArtifact: {
+        name: 'play-artifact-runtime';
+        currentVersion: number;
+        supportedVersions: readonly number[];
+    };
+    release: {
+        name: 'production-sdk-release';
+        /** npm may publish only from the active, healthy Production SHA. */
+        publishFrom: 'latest-successful-production-deployment';
+        /** A newer merge cancels an in-flight decision; reconciliation picks the last healthy SHA. */
+        coalesce: 'latest-healthy';
+    };
+};
+type SdkSupportPolicy = {
+    /**
+     * Anything strictly below this returns `status: "unsupported"` from
+     * `/api/v2/sdk/compat` and the CLI must hard-fail with the update command.
+     * Only advance after the support window closes.
+     */
+    minimumSupported: string;
+    /**
+     * Anything strictly below this returns `status: "deprecated"` (still works,
+     * warns). Advance when a release becomes the new floor.
+     */
+    deprecatedBelow: string;
+    /**
+     * Command-scoped support floors for SDK CLI workflows whose local behavior
+     * can break while the network API contract remains compatible.
+     */
+    commandMinimumSupported?: ReadonlyArray<{
+        command: string;
+        displayCommand?: string;
+        minimumSupported: string;
+        reason: string;
+    }>;
+    /**
+     * The version that first shipped a command.
+     *
+     * Deliberately not a support floor. `commandMinimumSupported` says an older
+     * client is BROKEN for a command and forces an update; this says only that
+     * an older client never had the command at all. That difference matters in
+     * both directions: introducing a command must not independently require an
+     * update, and a support floor may not exceed the version being released,
+     * while an introduction version is a fact about an already-published
+     * release. The general default-on freshness policy may still update an older
+     * installed CLI.
+     *
+     * It exists because agent skills are served by the backend and re-synced on
+     * nearly every CLI invocation, while the CLI stays pinned. A release that
+     * adds a command and documents it in the same commit therefore hands every
+     * installed client instructions it cannot follow, and `unknown command` is
+     * all the author sees. Recording the version lets the CLI say which release
+     * added it. `check:skill-cli-commands` requires an entry here before a skill
+     * may document a command.
+     */
+    commandIntroducedIn?: ReadonlyArray<{
+        command: string;
+        introducedIn: string;
+        reason: string;
+    }>;
+    /** Previously published wire contracts that remain supported. */
+    compatibleApiContracts?: readonly string[];
+    /**
+     * Published package versions that must keep working for direct SDK tool
+     * callers. CI installs each package from npm and exercises `tools.get` and
+     * `tools.execute` without involving the CLI or Play runtime.
+     */
+    directToolsCompatibilityVersions?: readonly string[];
+    /**
+     * Diagnostic freshness threshold reported by `/api/v2/sdk/compat`.
+     * Ownership-aware installed CLIs auto-update when older; this value remains
+     * metadata for clients and operational diagnostics.
+     */
+    autoUpdatePatchLag?: number;
+};
+type SdkRelease = {
+    /**
+     * Version published to npm. Usually stamped by the release workflow at
+     * publish time (auto-bump); edit by hand only for minor/major releases.
+     */
+    version: string;
+    /**
+     * One concise, agent-readable explanation shown while this release is an
+     * available update. Keep it actionable; the compatibility route includes it
+     * in its existing update message so older installed CLIs can print it too.
+     */
+    updateSummary?: string;
+    /** Capabilities stamped into the published package's `deepline` metadata. */
+    packageCapabilities: {
+        updatePreferences: 1;
+    };
+    /** Named compatibility policies. This is the only authored contract policy. */
+    contracts: DeeplineContractPolicy;
+    /** Public support policy reported by `/api/v2/sdk/compat`. */
+    supportPolicy: SdkSupportPolicy;
+};
+declare const SDK_RELEASE: {
+    readonly version: "0.3.90";
+    readonly updateSummary: "Play grep now uses one source-only Convex full-text index. It no longer scans the registry, pages through the complete indexed match set, and rejects retired grep modes. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
+    readonly packageCapabilities: {
+        readonly updatePreferences: 1;
+    };
+    readonly contracts: {
+        readonly api: {
+            readonly name: "sdk-http-api";
+            readonly currentMajor: 3;
+            readonly supportedMajors: readonly [3, 2];
+            readonly legacyWireIds: readonly ["2026-09-play-grep-convex-index-hard-cutover", "2026-07-admin-cli-local-cutover", "2026-07-native-monitor-launch-hard-cutover"];
+        };
+        readonly playArtifact: {
+            readonly name: "play-artifact-runtime";
+            readonly currentVersion: 2;
+            readonly supportedVersions: readonly [1, 2];
+        };
+        readonly release: {
+            readonly name: "production-sdk-release";
+            readonly publishFrom: "latest-successful-production-deployment";
+            readonly coalesce: "latest-healthy";
+        };
+    };
+    readonly supportPolicy: {
+        readonly minimumSupported: "0.1.53";
+        readonly deprecatedBelow: "0.3.1";
+        readonly commandIntroducedIn: readonly [{
+            readonly command: "notifications";
+            readonly introducedIn: "0.2.40";
+            readonly reason: "deepline notifications was added in SDK CLI 0.2.40. Older versions have no way to configure a Play failure alert, so a cron Play that dies reports to nobody.";
+        }];
+        readonly commandMinimumSupported: readonly [{
+            readonly command: "enrich";
+            readonly minimumSupported: "0.1.238";
+            readonly reason: "Older SDK CLI enrich generated stale play source; SDK CLI enrich 0.1.153 generated removed StepOptions fields in play source; SDK CLI enrich before 0.1.175 could silently succeed on the empty-waterfall bug when a requested waterfall returned no values for selected rows; SDK CLI enrich before 0.1.230 could convert extractor failures into successful unmatched results; SDK CLI enrich before 0.1.238 could drop a nested provider email match during generic pick(\"email\") extraction and materialize it as NO_MATCH.";
+        }, {
+            readonly command: "plays";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play results and can emit the retired esm_workers artifact contract. Update before checking, publishing, or running plays.";
+        }, {
+            readonly command: "plays run";
+            readonly minimumSupported: "0.1.253";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play results and can emit the retired esm_workers artifact contract; versions before 0.1.253 open the play page by default and accept the removed --no-open flag.";
+        }, {
+            readonly command: "run";
+            readonly displayCommand: "plays run";
+            readonly minimumSupported: "0.1.253";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play results and can emit the retired esm_workers artifact contract; versions before 0.1.253 open the play page by default and accept the removed --no-open flag.";
+        }, {
+            readonly command: "plays check";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play authoring and validate against the retired esm_workers artifact contract.";
+        }, {
+            readonly command: "check";
+            readonly displayCommand: "plays check";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play authoring and validate against the retired esm_workers artifact contract.";
+        }, {
+            readonly command: "plays publish";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play artifacts and can publish the retired esm_workers artifact contract.";
+        }, {
+            readonly command: "publish";
+            readonly displayCommand: "plays publish";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play artifacts and can publish the retired esm_workers artifact contract.";
+        }, {
+            readonly command: "plays set-live";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play artifacts and can publish the retired esm_workers artifact contract.";
+        }, {
+            readonly command: "set-live";
+            readonly displayCommand: "plays set-live";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play artifacts and can publish the retired esm_workers artifact contract.";
+        }, {
+            readonly command: "runs";
+            readonly minimumSupported: "0.1.111";
+            readonly reason: "Run result rows now render as dataset handles with explicit export commands.";
+        }, {
+            readonly command: "runs get";
+            readonly minimumSupported: "0.1.111";
+            readonly reason: "Run result rows now render as dataset handles with explicit export commands.";
+        }, {
+            readonly command: "get";
+            readonly displayCommand: "runs get";
+            readonly minimumSupported: "0.1.111";
+            readonly reason: "Run result rows now render as dataset handles with explicit export commands.";
+        }, {
+            readonly command: "runs export";
+            readonly minimumSupported: "0.1.111";
+            readonly reason: "Run result row datasets now use the dataset-handle export contract.";
+        }, {
+            readonly command: "export";
+            readonly displayCommand: "runs export";
+            readonly minimumSupported: "0.1.111";
+            readonly reason: "Run result row datasets now use the dataset-handle export contract.";
+        }];
+        readonly directToolsCompatibilityVersions: readonly ["0.1.171"];
+        readonly autoUpdatePatchLag: 2;
+    };
+};
+
+export { type DeeplineContractPolicy, SDK_RELEASE, type SdkRelease, type SdkReleaseChannel, type SdkSupportPolicy };

package/dist/release.d.ts

@@ -0,0 +1,255 @@
+/// <reference path="./text-imports.d.ts" />
+/**
+ * Single source of truth for SDK release metadata.
+ *
+ * Ordinary SDK PRs do NOT bump `version` here. Patch version selection
+ * happens at publish time: on push to main, `.github/workflows/sdk-release.yml`
+ * (via `scripts/sdk-release-autobump.ts`) compares the built package against
+ * the latest published npm tarball and, when the content changed, stamps the
+ * next unpublished patch into `version` in the CI workspace only and
+ * publishes it in the same run. That patch stamp is not
+ * committed back to main; production endpoints read npm metadata when they
+ * need the newest patch-level SDK/CLI version.
+ *
+ * Edit THIS file by hand only for deliberate release decisions:
+ *   - minor/major version bumps (set `version`),
+ *   - API-major cutovers (set `contracts.api.currentMajor`; leave `version` to the
+ *     publish-time patch selector),
+ *   - support-window moves (`minimumSupported` / `deprecatedBelow`).
+ * The automation never touches API compatibility policy, `minimumSupported`, or
+ * `deprecatedBelow`.
+ *
+ * Everything else derives from these values:
+ *
+ *   - `packages/sdk/src/version.ts` re-exports `SDK_VERSION` and `SDK_API_CONTRACT`.
+ *   - `apps/deepline-api/src/lib/sdk/release-policy.ts` re-exports `SDK_RELEASE_POLICY`.
+ *   - `packages/sdk/package.json` `version` is stamped from `SDK_RELEASE.version` by
+ *     `scripts/sync-sdk-package-version.ts`, which runs as part of
+ *     `bun run sdk:build`.
+ *   - `contracts/sdk-api.manifest.json` is regenerated at build time from
+ *     `apps/deepline-api/src/lib/sdk/api-routes.ts` and the apiContract here; the matching
+ *     `contracts/sdk-api.manifest.hash` is an ignored local/CI audit artifact.
+ *
+ * Any drift between release source and derived release locations is a
+ * `check:sdk-release-readiness` failure with a one-shot fix command; SDK/API
+ * compatibility policy is enforced by `bun run sdk:api-contract:check`.
+ */
+type SdkReleaseChannel = 'latest' | 'next' | 'beta';
+/**
+ * The named public protocols. These are intentionally independent:
+ *
+ * - `api` is the HTTP SDK/CLI protocol. It is additive within a major.
+ * - `playArtifact` is the immutable client-bundled Play payload ABI.
+ * - `release` controls promotion/publishing; it is not a client protocol.
+ *
+ * Do not use an SDK package version or a date string as an artifact ABI.
+ */
+type DeeplineContractPolicy = {
+    api: {
+        name: 'sdk-http-api';
+        currentMajor: number;
+        supportedMajors: readonly number[];
+        /** Transitional value for installed SDKs that only send the old header. */
+        legacyWireIds: readonly string[];
+    };
+    playArtifact: {
+        name: 'play-artifact-runtime';
+        currentVersion: number;
+        supportedVersions: readonly number[];
+    };
+    release: {
+        name: 'production-sdk-release';
+        /** npm may publish only from the active, healthy Production SHA. */
+        publishFrom: 'latest-successful-production-deployment';
+        /** A newer merge cancels an in-flight decision; reconciliation picks the last healthy SHA. */
+        coalesce: 'latest-healthy';
+    };
+};
+type SdkSupportPolicy = {
+    /**
+     * Anything strictly below this returns `status: "unsupported"` from
+     * `/api/v2/sdk/compat` and the CLI must hard-fail with the update command.
+     * Only advance after the support window closes.
+     */
+    minimumSupported: string;
+    /**
+     * Anything strictly below this returns `status: "deprecated"` (still works,
+     * warns). Advance when a release becomes the new floor.
+     */
+    deprecatedBelow: string;
+    /**
+     * Command-scoped support floors for SDK CLI workflows whose local behavior
+     * can break while the network API contract remains compatible.
+     */
+    commandMinimumSupported?: ReadonlyArray<{
+        command: string;
+        displayCommand?: string;
+        minimumSupported: string;
+        reason: string;
+    }>;
+    /**
+     * The version that first shipped a command.
+     *
+     * Deliberately not a support floor. `commandMinimumSupported` says an older
+     * client is BROKEN for a command and forces an update; this says only that
+     * an older client never had the command at all. That difference matters in
+     * both directions: introducing a command must not independently require an
+     * update, and a support floor may not exceed the version being released,
+     * while an introduction version is a fact about an already-published
+     * release. The general default-on freshness policy may still update an older
+     * installed CLI.
+     *
+     * It exists because agent skills are served by the backend and re-synced on
+     * nearly every CLI invocation, while the CLI stays pinned. A release that
+     * adds a command and documents it in the same commit therefore hands every
+     * installed client instructions it cannot follow, and `unknown command` is
+     * all the author sees. Recording the version lets the CLI say which release
+     * added it. `check:skill-cli-commands` requires an entry here before a skill
+     * may document a command.
+     */
+    commandIntroducedIn?: ReadonlyArray<{
+        command: string;
+        introducedIn: string;
+        reason: string;
+    }>;
+    /** Previously published wire contracts that remain supported. */
+    compatibleApiContracts?: readonly string[];
+    /**
+     * Published package versions that must keep working for direct SDK tool
+     * callers. CI installs each package from npm and exercises `tools.get` and
+     * `tools.execute` without involving the CLI or Play runtime.
+     */
+    directToolsCompatibilityVersions?: readonly string[];
+    /**
+     * Diagnostic freshness threshold reported by `/api/v2/sdk/compat`.
+     * Ownership-aware installed CLIs auto-update when older; this value remains
+     * metadata for clients and operational diagnostics.
+     */
+    autoUpdatePatchLag?: number;
+};
+type SdkRelease = {
+    /**
+     * Version published to npm. Usually stamped by the release workflow at
+     * publish time (auto-bump); edit by hand only for minor/major releases.
+     */
+    version: string;
+    /**
+     * One concise, agent-readable explanation shown while this release is an
+     * available update. Keep it actionable; the compatibility route includes it
+     * in its existing update message so older installed CLIs can print it too.
+     */
+    updateSummary?: string;
+    /** Capabilities stamped into the published package's `deepline` metadata. */
+    packageCapabilities: {
+        updatePreferences: 1;
+    };
+    /** Named compatibility policies. This is the only authored contract policy. */
+    contracts: DeeplineContractPolicy;
+    /** Public support policy reported by `/api/v2/sdk/compat`. */
+    supportPolicy: SdkSupportPolicy;
+};
+declare const SDK_RELEASE: {
+    readonly version: "0.3.90";
+    readonly updateSummary: "Play grep now uses one source-only Convex full-text index. It no longer scans the registry, pages through the complete indexed match set, and rejects retired grep modes. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.";
+    readonly packageCapabilities: {
+        readonly updatePreferences: 1;
+    };
+    readonly contracts: {
+        readonly api: {
+            readonly name: "sdk-http-api";
+            readonly currentMajor: 3;
+            readonly supportedMajors: readonly [3, 2];
+            readonly legacyWireIds: readonly ["2026-09-play-grep-convex-index-hard-cutover", "2026-07-admin-cli-local-cutover", "2026-07-native-monitor-launch-hard-cutover"];
+        };
+        readonly playArtifact: {
+            readonly name: "play-artifact-runtime";
+            readonly currentVersion: 2;
+            readonly supportedVersions: readonly [1, 2];
+        };
+        readonly release: {
+            readonly name: "production-sdk-release";
+            readonly publishFrom: "latest-successful-production-deployment";
+            readonly coalesce: "latest-healthy";
+        };
+    };
+    readonly supportPolicy: {
+        readonly minimumSupported: "0.1.53";
+        readonly deprecatedBelow: "0.3.1";
+        readonly commandIntroducedIn: readonly [{
+            readonly command: "notifications";
+            readonly introducedIn: "0.2.40";
+            readonly reason: "deepline notifications was added in SDK CLI 0.2.40. Older versions have no way to configure a Play failure alert, so a cron Play that dies reports to nobody.";
+        }];
+        readonly commandMinimumSupported: readonly [{
+            readonly command: "enrich";
+            readonly minimumSupported: "0.1.238";
+            readonly reason: "Older SDK CLI enrich generated stale play source; SDK CLI enrich 0.1.153 generated removed StepOptions fields in play source; SDK CLI enrich before 0.1.175 could silently succeed on the empty-waterfall bug when a requested waterfall returned no values for selected rows; SDK CLI enrich before 0.1.230 could convert extractor failures into successful unmatched results; SDK CLI enrich before 0.1.238 could drop a nested provider email match during generic pick(\"email\") extraction and materialize it as NO_MATCH.";
+        }, {
+            readonly command: "plays";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play results and can emit the retired esm_workers artifact contract. Update before checking, publishing, or running plays.";
+        }, {
+            readonly command: "plays run";
+            readonly minimumSupported: "0.1.253";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play results and can emit the retired esm_workers artifact contract; versions before 0.1.253 open the play page by default and accept the removed --no-open flag.";
+        }, {
+            readonly command: "run";
+            readonly displayCommand: "plays run";
+            readonly minimumSupported: "0.1.253";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play results and can emit the retired esm_workers artifact contract; versions before 0.1.253 open the play page by default and accept the removed --no-open flag.";
+        }, {
+            readonly command: "plays check";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play authoring and validate against the retired esm_workers artifact contract.";
+        }, {
+            readonly command: "check";
+            readonly displayCommand: "plays check";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play authoring and validate against the retired esm_workers artifact contract.";
+        }, {
+            readonly command: "plays publish";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play artifacts and can publish the retired esm_workers artifact contract.";
+        }, {
+            readonly command: "publish";
+            readonly displayCommand: "plays publish";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play artifacts and can publish the retired esm_workers artifact contract.";
+        }, {
+            readonly command: "plays set-live";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play artifacts and can publish the retired esm_workers artifact contract.";
+        }, {
+            readonly command: "set-live";
+            readonly displayCommand: "plays set-live";
+            readonly minimumSupported: "0.1.241";
+            readonly reason: "Older SDK CLI versions predate dataset-native Play artifacts and can publish the retired esm_workers artifact contract.";
+        }, {
+            readonly command: "runs";
+            readonly minimumSupported: "0.1.111";
+            readonly reason: "Run result rows now render as dataset handles with explicit export commands.";
+        }, {
+            readonly command: "runs get";
+            readonly minimumSupported: "0.1.111";
+            readonly reason: "Run result rows now render as dataset handles with explicit export commands.";
+        }, {
+            readonly command: "get";
+            readonly displayCommand: "runs get";
+            readonly minimumSupported: "0.1.111";
+            readonly reason: "Run result rows now render as dataset handles with explicit export commands.";
+        }, {
+            readonly command: "runs export";
+            readonly minimumSupported: "0.1.111";
+            readonly reason: "Run result row datasets now use the dataset-handle export contract.";
+        }, {
+            readonly command: "export";
+            readonly displayCommand: "runs export";
+            readonly minimumSupported: "0.1.111";
+            readonly reason: "Run result row datasets now use the dataset-handle export contract.";
+        }];
+        readonly directToolsCompatibilityVersions: readonly ["0.1.171"];
+        readonly autoUpdatePatchLag: 2;
+    };
+};
+
+export { type DeeplineContractPolicy, SDK_RELEASE, type SdkRelease, type SdkReleaseChannel, type SdkSupportPolicy };