deprecate(sdk): the v0.3 package.meta.json prototype and workspace discovery

These ten sdk exports model a package.meta.json that nothing in the
toolchain ever reads: no loader, CLI or port consults it, and the only
callers are the sdk's own tests. Cross-repo metadata sharing is being
built properly as FR-023 (metadata dependencies), so the prototype would
mislead anyone who found it first. They are public exports, so they stay
working now and are removed in 2.0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ApQWqotP1jaKs85XhKVXG4

Author: dmealing

CHANGELOG.md

@@ -10,6 +10,15 @@ here.**
 
 ## [Unreleased]
 
+### Deprecated
+
+- **`@metaobjectsdev/sdk`: the v0.3 `package.meta.json` prototype and workspace discovery** —
+  `PackageManifestSchema`, `PackageManifest`, `PACKAGE_MANIFEST_FILE`, `readPackageManifest`,
+  `resolveMetaobjectsPackage`, `discoverWorkspace`, `resolveExtendsOrder`, `packageLabel`,
+  `Workspace`, `WorkspacePackage`. Nothing in the toolchain reads a `package.meta.json`;
+  cross-repo metadata sharing is being built as FR-023 (metadata dependencies). They still work
+  and are removed in 2.0.
+
 ## [1.0.2] — 2026-09-11
 
 _npm `1.0.2` (full lockstep across all 14 `@metaobjectsdev/*` publish candidates)._

server/typescript/packages/sdk/src/index.ts

@@ -94,15 +94,13 @@ export type { DiscoveredRoot } from "./discovery.js";
 export { resolveCollection } from "./collection.js";
 export type { Collection } from "./collection.js";
 
-// Workspace discovery — finds peer metadata packages in a monorepo
+// DEPRECATED (removed in 2.0) — workspace discovery over the v0.3 package.meta.json
+// prototype. Nothing in the toolchain calls it; cross-repo sharing is FR-023.
 export { discoverWorkspace, resolveExtendsOrder, packageLabel } from "./workspace.js";
 export type { Workspace, WorkspacePackage } from "./workspace.js";
 
-// Package manifest — the v0.3 package.meta.json model. Three-field manifest
-// (name, version, extends) that defines a metadata package's identity and
-// upstream dependencies. The package's metadata tree IS its public API;
-// there is no exports field. See docs/strategy/2026-05-12-v0.3-ai-first-
-// metadata-loading.md.
+// DEPRECATED (removed in 2.0) — the v0.3 package.meta.json prototype. Never wired into
+// loading; superseded by FR-023 (metadata dependencies).
 export {
   PackageManifestSchema,
   readPackageManifest,

server/typescript/packages/sdk/src/package.ts

@@ -39,6 +39,8 @@ const MetaobjectsPackageSchema = z.string().regex(
 /**
  * The package.meta.json schema. Authoring this is the one-time cost of
  * defining a metadata package; subsequent edits should be rare.
+ *
+ * @deprecated The v0.3 `package.meta.json` prototype: nothing in the toolchain reads it. Cross-repo metadata sharing is FR-023 (metadata dependencies). Removed in 2.0.
  */
 export const PackageManifestSchema = z.object({
   /**
@@ -72,15 +74,19 @@ export const PackageManifestSchema = z.object({
   extends: z.array(ExtendsEntrySchema).default([]),
 });
 
+/** @deprecated The v0.3 `package.meta.json` prototype: nothing in the toolchain reads it. Cross-repo metadata sharing is FR-023 (metadata dependencies). Removed in 2.0. */
 export type PackageManifest = z.infer<typeof PackageManifestSchema>;
 
+/** @deprecated The v0.3 `package.meta.json` prototype: nothing in the toolchain reads it. Cross-repo metadata sharing is FR-023 (metadata dependencies). Removed in 2.0. */
 export const PACKAGE_MANIFEST_FILE = "package.meta.json";
 
 /**
  * Read a package.meta.json from a given .meta/ root, if present.
  * Returns undefined when the file isn't there — packages are optional in
  * v0.3 v0.1 (loadMemory still works for single-package usage without one,
  * and forge init scaffolds one but doesn't enforce its presence).
+ *
+ * @deprecated The v0.3 `package.meta.json` prototype: nothing in the toolchain reads it. Cross-repo metadata sharing is FR-023 (metadata dependencies). Removed in 2.0.
  */
 export async function readPackageManifest(metaDir: string): Promise<PackageManifest | undefined> {
   const path = join(metaDir, PACKAGE_MANIFEST_FILE);
@@ -104,6 +110,8 @@ export async function readPackageManifest(metaDir: string): Promise<PackageManif
  * Returns undefined if `name` itself isn't a valid bare name (e.g. has
  * uppercase chars) and no explicit ref is set — the caller should treat
  * this as an authoring error.
+ *
+ * @deprecated The v0.3 `package.meta.json` prototype: nothing in the toolchain reads it. Cross-repo metadata sharing is FR-023 (metadata dependencies). Removed in 2.0.
  */
 export function resolveMetaobjectsPackage(manifest: PackageManifest): string | undefined {
   if (manifest.metaobjectsPackage !== undefined) return manifest.metaobjectsPackage;

server/typescript/packages/sdk/src/workspace.ts

@@ -30,6 +30,7 @@ const PACKAGE_JSON = "package.json";
 // Public types
 // ---------------------------------------------------------------------------
 
+/** @deprecated The v0.3 `package.meta.json` prototype: nothing in the toolchain reads it. Cross-repo metadata sharing is FR-023 (metadata dependencies). Removed in 2.0. */
 export interface WorkspacePackage {
   /** Absolute path to the .meta/ directory. */
   metaDir: string;
@@ -39,6 +40,7 @@ export interface WorkspacePackage {
   metaobjectsPackage: string;
 }
 
+/** @deprecated The v0.3 `package.meta.json` prototype: nothing in the toolchain reads it. Cross-repo metadata sharing is FR-023 (metadata dependencies). Removed in 2.0. */
 export interface Workspace {
   /** Absolute path to the workspace root (where pnpm-workspace.yaml or package.json lives). */
   root: string;
@@ -213,6 +215,8 @@ function matchGlobSegment(pattern: string): (value: string) => boolean {
  *
  * The returned Workspace has every package's manifest pre-loaded; callers
  * can look up peers by name or canonical metaobjects ref.
+ *
+ * @deprecated The v0.3 `package.meta.json` prototype: nothing in the toolchain reads it. Cross-repo metadata sharing is FR-023 (metadata dependencies). Removed in 2.0.
  */
 export async function discoverWorkspace(cwd: string): Promise<Workspace | undefined> {
   const config = await findWorkspaceConfig(cwd);
@@ -290,6 +294,8 @@ export async function discoverWorkspace(cwd: string): Promise<Workspace | undefi
  * Throws on:
  *   - Missing package referenced by extends:
  *   - Cycles in the extends graph
+ *
+ * @deprecated The v0.3 `package.meta.json` prototype: nothing in the toolchain reads it. Cross-repo metadata sharing is FR-023 (metadata dependencies). Removed in 2.0.
  */
 export function resolveExtendsOrder(
   workspace: Workspace,
@@ -336,7 +342,11 @@ export function resolveExtendsOrder(
 // Diagnostic helpers
 // ---------------------------------------------------------------------------
 
-/** Human-readable label for a workspace package — useful for error messages. */
+/**
+ * Human-readable label for a workspace package — useful for error messages.
+ *
+ * @deprecated The v0.3 `package.meta.json` prototype: nothing in the toolchain reads it. Cross-repo metadata sharing is FR-023 (metadata dependencies). Removed in 2.0.
+ */
 export function packageLabel(pkg: WorkspacePackage): string {
   return `${pkg.manifest.name} (${pkg.metaobjectsPackage}) at ${basename(dirname(pkg.metaDir))}`;
 }