@company-semantics/contracts 0.95.0 → 0.97.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.95.0",
+  "version": "0.97.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/index.ts

@@ -250,6 +250,23 @@ export type {
   GoalDependency,
   GoalTreeNode,
   GoalDoc,
+  // Team types (PRD-00306)
+  TeamMembershipRole,
+  TeamSyncMode,
+  Team,
+  TeamMember,
+  TeamDetail,
+  // Sharing and ACL types (PRD-00306)
+  AccessLevel,
+  SharePolicy,
+  AclEntry,
+  AccessSource,
+  AccessReason,
+  EffectiveAccess,
+  EvaluationStep,
+  AccessExplanation,
+  ShareState,
+  PermissionAuditEntry,
 } from './org/index'
 
 export { ROLE_DISPLAY_MAP, VIEW_SCOPE_MAP, getViewScope, TRANSFER_RESPONSIBILITIES, IDENTITY_TRUST_LEVEL_LABELS } from './org/index'

package/src/org/__tests__/view-scopes.test.ts

@@ -6,12 +6,14 @@ describe('VIEW_SCOPE_MAP golden snapshot', () => {
     expect(VIEW_SCOPE_MAP).toStrictEqual({
       workspace: 'org.view_workspace',
       timeline: 'org.view_timeline',
-      activity: 'org.view_activity',
+      teamwork: 'org.view_teamwork',
       goals: 'org.view_goals',
+      teams: 'org.view_teams',
       'internal-admin': 'internal.view_admin',
       chat: null,
       settings: null,
       chats: null,
+      'my-work': null,
       upgrade: null,
     })
   })
@@ -21,7 +23,7 @@ describe('getViewScope', () => {
   it('returns the required scope for protected views', () => {
     expect(getViewScope('workspace')).toBe('org.view_workspace')
     expect(getViewScope('timeline')).toBe('org.view_timeline')
-    expect(getViewScope('activity')).toBe('org.view_activity')
+    expect(getViewScope('teamwork')).toBe('org.view_teamwork')
     expect(getViewScope('goals')).toBe('org.view_goals')
     expect(getViewScope('internal-admin')).toBe('internal.view_admin')
   })

package/src/org/goals.ts

@@ -8,7 +8,7 @@
 
 export type GoalVisibility = 'public' | 'private';
 
-export type GoalDocLevel = 'root' | 'department';
+export type GoalDocLevel = 'root' | 'department' | 'team';
 
 export interface GoalSource {
   readonly label: string;
@@ -30,6 +30,8 @@ export interface GoalTreeNode {
   readonly visibility: GoalVisibility;
   readonly canEdit: boolean;
   readonly memberCount: number;
+  /** Owning team. Null for root docs or when the owning team has been deleted. */
+  readonly owningTeam: { readonly id: string; readonly name: string } | null;
 }
 
 export interface GoalDocCore {
@@ -41,6 +43,8 @@ export interface GoalDocCore {
   readonly content: string;
   readonly visibility: GoalVisibility;
   readonly parentId: string | null;
+  /** Owning team. Null for root docs or when the owning team has been deleted. */
+  readonly owningTeam: { readonly id: string; readonly name: string } | null;
 }
 
 export interface GoalDocCollaborators {

package/src/org/index.ts

@@ -92,3 +92,26 @@ export type {
   GoalDocRelations,
   GoalDoc,
 } from './goals';
+
+// Team types (PRD-00306)
+export type {
+  TeamMembershipRole,
+  TeamSyncMode,
+  Team,
+  TeamMember,
+  TeamDetail,
+} from './teams';
+
+// Sharing and ACL types (PRD-00306)
+export type {
+  AccessLevel,
+  SharePolicy,
+  AclEntry,
+  AccessSource,
+  AccessReason,
+  EffectiveAccess,
+  EvaluationStep,
+  AccessExplanation,
+  ShareState,
+  PermissionAuditEntry,
+} from './sharing';

package/src/org/sharing.ts

@@ -0,0 +1,97 @@
+/**
+ * Document access level.
+ * Privilege order: editor > commenter > viewer.
+ */
+export type AccessLevel = 'viewer' | 'commenter' | 'editor';
+
+/**
+ * Document sharing policy.
+ * - restricted: Only explicit ACL + owning team + org admins
+ * - org_read: All org members can view
+ * - org_comment: All org members can comment
+ * - org_edit: All org members can edit (does NOT imply canShare)
+ */
+export type SharePolicy = 'restricted' | 'org_read' | 'org_comment' | 'org_edit';
+
+export interface AclEntry {
+  readonly principalType: 'user' | 'team';
+  readonly principalId: string;
+  readonly principalName: string;
+  readonly accessLevel: AccessLevel;
+  readonly grantedBy: { readonly id: string; readonly name: string } | null;
+  readonly grantedAt: string;
+}
+
+/**
+ * Source of an access grant.
+ * Used in EffectiveAccess.reasons and EvaluationStep.source.
+ */
+export type AccessSource = 'org_rbac' | 'sharing_policy' | 'team_baseline' | 'acl_grant' | 'doc_ownership';
+
+export interface AccessReason {
+  readonly source: AccessSource;
+  readonly detail: string;
+}
+
+/**
+ * Effective access for a user on a document.
+ *
+ * INVARIANTS:
+ * - canShare is granted ONLY by: doc ownership, team ownership of owning team,
+ *   or org-level org.manage_goals / org.manage_teams.
+ * - canShare is NEVER granted by ACL entries or sharing policy.
+ * - org_edit via sharing policy does NOT imply canShare.
+ * - Team membership grants baseline access ONLY to resources owned by that team.
+ */
+export interface EffectiveAccess {
+  readonly level: 'none' | AccessLevel;
+  readonly reasons: ReadonlyArray<AccessReason>;
+  readonly canShare: boolean;
+}
+
+/**
+ * Single step in the access evaluation trace.
+ * Enables full traceability for debugging, audit UI, and compliance.
+ */
+export interface EvaluationStep {
+  readonly source: AccessSource;
+  readonly checked: boolean;
+  readonly granted: AccessLevel | null;
+  readonly detail: string;
+}
+
+/**
+ * Full access explanation with evaluation trace.
+ * Returned by GoalsAccessEvaluator.explain().
+ */
+export interface AccessExplanation extends EffectiveAccess {
+  readonly evaluationTrace: ReadonlyArray<EvaluationStep>;
+}
+
+/**
+ * Complete sharing state for a document.
+ * Returned by GET /api/goals/docs/:slug/sharing.
+ */
+export interface ShareState {
+  readonly sharingPolicy: SharePolicy;
+  readonly acl: ReadonlyArray<AclEntry>;
+  readonly effectiveAccess: EffectiveAccess;
+}
+
+/**
+ * Single entry in the permission change audit log.
+ * Used by audit views to display a history of permission changes.
+ */
+export interface PermissionAuditEntry {
+  readonly action: 'granted' | 'revoked' | 'updated';
+  readonly resourceType: 'goals_doc' | 'team';
+  readonly resourceId: string;
+  readonly resourceName: string;
+  readonly principalType: 'user' | 'team';
+  readonly principalId: string;
+  readonly principalName: string;
+  readonly detail: string;
+  readonly actorId: string;
+  readonly actorName: string;
+  readonly timestamp: string;
+}

package/src/org/teams.ts

@@ -0,0 +1,46 @@
+/**
+ * Team membership role.
+ * Privilege order: owner > manager > member.
+ * Effective role = max(role by privilege) across all active rows for a (team_id, user_id) pair.
+ * Rows with status != 'active' are ignored.
+ */
+export type TeamMembershipRole = 'member' | 'manager' | 'owner';
+
+/**
+ * Team membership sync mode.
+ * - manual_only: All in-app membership mutations allowed
+ * - synced_readonly: Rejects all in-app membership changes (external source is authority)
+ * - synced_with_overrides: Allows manual additions; sync-sourced rows are read-only
+ */
+export type TeamSyncMode = 'manual_only' | 'synced_readonly' | 'synced_with_overrides';
+
+/**
+ * Team read model for list views.
+ */
+export interface Team {
+  readonly id: string;
+  readonly name: string;
+  readonly slug: string;
+  readonly description: string | null;
+  readonly memberCount: number;
+}
+
+/**
+ * Team member within a team detail view.
+ */
+export interface TeamMember {
+  readonly userId: string;
+  readonly name: string;
+  readonly email: string;
+  readonly role: TeamMembershipRole;
+  readonly joinedAt: string;
+}
+
+/**
+ * Full team detail view including members.
+ * Returned by GET /api/teams/:teamId.
+ */
+export interface TeamDetail extends Team {
+  readonly members: ReadonlyArray<TeamMember>;
+  readonly syncMode: TeamSyncMode;
+}

package/src/org/view-scopes.ts

@@ -19,13 +19,15 @@ export const VIEW_SCOPE_MAP = {
   // Protected views (require specific scope)
   workspace: 'org.view_workspace',
   timeline: 'org.view_timeline',
-  activity: 'org.view_activity',
+  teamwork: 'org.view_teamwork',
   goals: 'org.view_goals',
+  teams: 'org.view_teams',
   'internal-admin': 'internal.view_admin',
   // Public views (require only authentication)
   chat: null,
   settings: null,
   chats: null,
+  'my-work': null,
   upgrade: null,
 } as const;