Define the public boundary once. NetScript carries it through the stack.

// From the workspace root:
// netscript db generate --db postgres

// contracts/versions/v1/users.schemas.ts
import { UserSchema as DatabaseUserSchema } from '@database/zod';
import { z } from 'zod';

export const UsersListItemSchemaV1 = DatabaseUserSchema
  .pick({ id: true, name: true })
  .extend({
    status: z.enum(['active', 'invited']),
  });

// contracts/versions/v1/users.contract.ts
import { z } from 'zod';
import { oc } from '@orpc/contract';
import { implement } from '@orpc/server';
import { UsersListItemSchemaV1 } from './users.schemas.ts'; // derived in tab 0, or hand-authored without a database

export const UsersListInputSchemaV1 = z.object({
  limit: z.number().int().positive().max(100).default(20),
});

// The contract binds method + input + output. No handler yet.
export const UsersContractV1 = {
  list: oc.route({ method: 'POST' })
    .input(UsersListInputSchemaV1)
    .output(z.object({ items: z.array(UsersListItemSchemaV1) })),
};

export const UsersV1 = implement(UsersContractV1);

// services/users/src/routers/v1.ts
import { UsersV1 as usersContract } from '@my-app/contracts';

// `input` is typed from the contract. The return value must
// satisfy the contract's output schema — or it does not compile.
export const UsersV1 = {
  list: usersContract.list.handler(async ({ input }) => {
    const items = await listUsers({ limit: input.limit });
    return { items };
  }),
};

// services/users/src/main.ts
// defineService() serves the router with OpenAPI, typed RPC,
// health endpoints, and request logging wired in.
import { defineService } from '@netscript/service';
import { router } from './router.ts';

await defineService(router, { name: 'users', version: '1.0.0' });

// apps/dashboard/lib/users.ts
import { createServiceClient } from '@netscript/sdk/client';
import { createQueryFactories } from '@netscript/sdk/query';
import { UsersContractV1 } from '@my-app/contracts';

export const usersName = 'users';
export const usersRouterName = 'users';
export const usersContract = UsersContractV1;
export const usersClient = createServiceClient<typeof usersContract>({
  contract: usersContract,
  serviceName: usersName,
  routerName: usersRouterName,
});
export const usersQueries = createQueryFactories({
  service: { contract: usersContract, client: usersClient },
}).service;

// apps/dashboard/routes/users/index.tsx
import { definePage } from '@netscript/fresh/builders';
import { z } from 'zod';
import { usersQueries } from '@app/lib/users.ts';
import { routes } from '@app/router.ts';
import UsersTable from './(_islands)/UsersTable.tsx';

export const usersPage = definePage()
  .withRoute(routes.users.$route)
  .withSearchParams(z.object({
    limit: z.coerce.number().int().positive().max(100).default(20),
  }))
  .withLayer('users', UsersTable, {
    loader: async (ctx) => {
      const input = { limit: ctx.search.limit };
      // Server-only: getCachedEntry uses the registered cache provider.
      const entry = await usersQueries.list.getCachedEntry(input);
      if (entry) return { users: entry.data, cachedAt: entry.cachedAt };
      return {
        users: await usersQueries.list.queryOptions(input).queryFn(),
        cachedAt: Date.now(),
      };
    },
  })
  .withLayout((slots) => <main class='ns-page'>{slots.users()}</main>)
  .build();

export const { default: page } = usersPage;
export { page as default };